Skip to content

armgit / mimik

Public Imported from GitHub
0

🎬 A browser extension and desktop app that turns your clicks into step-by-step guides with annotated screenshots πŸ“–

feat(messaging): add on-demand guide description generation

Luis Ortiz5b4639bfddb4
diff --git a/src/entrypoints/background/__tests__/guide-meta.test.ts b/src/entrypoints/background/__tests__/guide-meta.test.ts
new file mode 100644
index 0000000..fa3d8f7
--- /dev/null
+++ b/src/entrypoints/background/__tests__/guide-meta.test.ts
@@ -0,0 +1,230 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const {
+ generateGuideMetaMock,
+ getGuideDomainMock,
+ getStepsForGuideMock,
+ localStorageGetMock,
+ updateGuideDescriptionMock,
+ updateGuideTitleMock,
+} = vi.hoisted(() => ({
+ generateGuideMetaMock: vi.fn(),
+ getGuideDomainMock: vi.fn(),
+ getStepsForGuideMock: vi.fn(),
+ localStorageGetMock: vi.fn(),
+ updateGuideDescriptionMock: vi.fn(),
+ updateGuideTitleMock: vi.fn(),
+}));
+
+vi.mock('@/core/capture/ai/meta', () => ({ generateGuideMeta: generateGuideMetaMock }));
+
+vi.mock('@/core/guides/service', () => ({
+ getGuideDomain: getGuideDomainMock,
+ getStepsForGuide: getStepsForGuideMock,
+ updateGuideDescription: updateGuideDescriptionMock,
+ updateGuideTitle: updateGuideTitleMock,
+}));
+
+vi.mock('@/lib/browser-api', () => ({ localStorage: { get: localStorageGetMock } }));
+
+import { AI_PROVIDERS } from '@/core/capture/ai/models';
+import { generateDescriptionOnDemand, generateGuideMetaOnStop } from '../guide-meta';
+
+const GUIDE_ID = 'guide-1';
+
+const entryPoints = [
+ ['generateGuideMetaOnStop', generateGuideMetaOnStop],
+ ['generateDescriptionOnDemand', generateDescriptionOnDemand],
+] as const;
+
+function makeSteps(count: number) {
+ return Array.from({ length: count }, (_, i) => ({
+ description: `step ${i}`,
+ url: `https://example.com/${i}`,
+ }));
+}
+
+describe('background guide-meta', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ localStorageGetMock.mockResolvedValue({ aiApiKey: 'key', aiProvider: 'openai', aiModel: 'gpt-4o' });
+ getStepsForGuideMock.mockResolvedValue(makeSteps(3));
+ getGuideDomainMock.mockResolvedValue('example.com');
+ updateGuideTitleMock.mockResolvedValue(undefined);
+ updateGuideDescriptionMock.mockResolvedValue(undefined);
+ generateGuideMetaMock.mockResolvedValue({ title: 'Generated Title', description: 'Generated description.' });
+ });
+
+ describe('input resolution shared by both entry points', () => {
+ it.each(entryPoints)('%s sends the first ten and last five of more than fifteen steps', async (_name, run) => {
+ getStepsForGuideMock.mockResolvedValue(makeSteps(20));
+
+ await run(GUIDE_ID);
+
+ const sent = generateGuideMetaMock.mock.calls[0][0];
+ expect(sent).toHaveLength(15);
+ expect(sent[0].description).toBe('step 0');
+ expect(sent[9].description).toBe('step 9');
+ expect(sent[10].description).toBe('step 15');
+ expect(sent[14].description).toBe('step 19');
+ });
+
+ it.each(entryPoints)('%s sends every step when there are exactly fifteen', async (_name, run) => {
+ getStepsForGuideMock.mockResolvedValue(makeSteps(15));
+
+ await run(GUIDE_ID);
+
+ expect(generateGuideMetaMock.mock.calls[0][0]).toHaveLength(15);
+ });
+
+ it.each(entryPoints)('%s drops steps that have no description', async (_name, run) => {
+ getStepsForGuideMock.mockResolvedValue([
+ { description: 'kept', url: 'https://example.com/a' },
+ { description: '', url: 'https://example.com/b' },
+ ]);
+
+ await run(GUIDE_ID);
+
+ expect(generateGuideMetaMock.mock.calls[0][0]).toEqual([{ description: 'kept', url: 'https://example.com/a' }]);
+ });
+
+ it.each(entryPoints)("%s defaults the model to the provider's own default", async (_name, run) => {
+ localStorageGetMock.mockResolvedValue({ aiApiKey: 'key', aiProvider: 'anthropic' });
+
+ await run(GUIDE_ID);
+
+ expect(generateGuideMetaMock).toHaveBeenCalledWith(
+ expect.anything(),
+ 'anthropic',
+ AI_PROVIDERS.anthropic.defaultModel,
+ 'key',
+ );
+ });
+
+ it.each(entryPoints)('%s defaults the provider to OpenAI when none is stored', async (_name, run) => {
+ localStorageGetMock.mockResolvedValue({ aiApiKey: 'key' });
+
+ await run(GUIDE_ID);
+
+ expect(generateGuideMetaMock).toHaveBeenCalledWith(
+ expect.anything(),
+ 'openai',
+ AI_PROVIDERS.openai.defaultModel,
+ 'key',
+ );
+ });
+ });
+
+ describe('generateGuideMetaOnStop', () => {
+ it('applies the domain fallback title without calling the model when no key is set', async () => {
+ localStorageGetMock.mockResolvedValue({});
+
+ await generateGuideMetaOnStop(GUIDE_ID);
+
+ expect(generateGuideMetaMock).not.toHaveBeenCalled();
+ expect(updateGuideTitleMock).toHaveBeenCalledWith(GUIDE_ID, 'background.guideOnDomain[example.com]');
+ });
+
+ it('falls back to the generic title when the guide has no domain', async () => {
+ localStorageGetMock.mockResolvedValue({});
+ getGuideDomainMock.mockResolvedValue('');
+
+ await generateGuideMetaOnStop(GUIDE_ID);
+
+ expect(updateGuideTitleMock).toHaveBeenCalledWith(GUIDE_ID, 'background.newGuide');
+ });
+
+ it('writes no title at all when no step has a description', async () => {
+ getStepsForGuideMock.mockResolvedValue([{ description: '', url: 'https://example.com' }]);
+
+ await generateGuideMetaOnStop(GUIDE_ID);
+
+ expect(generateGuideMetaMock).not.toHaveBeenCalled();
+ expect(updateGuideTitleMock).not.toHaveBeenCalled();
+ expect(updateGuideDescriptionMock).not.toHaveBeenCalled();
+ });
+
+ it('applies the fallback title when the model yields nothing', async () => {
+ generateGuideMetaMock.mockResolvedValue(null);
+
+ await generateGuideMetaOnStop(GUIDE_ID);
+
+ expect(updateGuideTitleMock).toHaveBeenCalledWith(GUIDE_ID, 'background.guideOnDomain[example.com]');
+ });
+
+ it('stores both the title and the description on success', async () => {
+ await generateGuideMetaOnStop(GUIDE_ID);
+
+ expect(updateGuideTitleMock).toHaveBeenCalledWith(GUIDE_ID, 'Generated Title');
+ expect(updateGuideDescriptionMock).toHaveBeenCalledWith(GUIDE_ID, 'Generated description.');
+ });
+
+ it('keeps the generated title when the description write fails', async () => {
+ updateGuideDescriptionMock.mockRejectedValue(new Error('QuotaExceededError'));
+
+ await generateGuideMetaOnStop(GUIDE_ID);
+
+ expect(updateGuideTitleMock).toHaveBeenCalledTimes(1);
+ expect(updateGuideTitleMock).toHaveBeenCalledWith(GUIDE_ID, 'Generated Title');
+ });
+
+ it('applies the fallback title when the title write itself fails', async () => {
+ updateGuideTitleMock.mockRejectedValueOnce(new Error('DatabaseClosedError'));
+
+ await generateGuideMetaOnStop(GUIDE_ID);
+
+ expect(updateGuideTitleMock).toHaveBeenNthCalledWith(2, GUIDE_ID, 'background.guideOnDomain[example.com]');
+ });
+ });
+
+ describe('generateDescriptionOnDemand', () => {
+ it('reports a missing key without touching the guide', async () => {
+ localStorageGetMock.mockResolvedValue({});
+
+ await expect(generateDescriptionOnDemand(GUIDE_ID)).resolves.toEqual({ error: 'no-api-key' });
+ expect(updateGuideTitleMock).not.toHaveBeenCalled();
+ expect(updateGuideDescriptionMock).not.toHaveBeenCalled();
+ });
+
+ it('reports a guide with no described steps', async () => {
+ getStepsForGuideMock.mockResolvedValue([]);
+
+ await expect(generateDescriptionOnDemand(GUIDE_ID)).resolves.toEqual({ error: 'no-steps' });
+ expect(generateGuideMetaMock).not.toHaveBeenCalled();
+ });
+
+ it('reports a failed generation', async () => {
+ generateGuideMetaMock.mockResolvedValue(null);
+
+ await expect(generateDescriptionOnDemand(GUIDE_ID)).resolves.toEqual({ error: 'generation-failed' });
+ expect(updateGuideDescriptionMock).not.toHaveBeenCalled();
+ });
+
+ it('reports a failed generation when the model returns a title but no description', async () => {
+ generateGuideMetaMock.mockResolvedValue({ title: 'Generated Title' });
+
+ await expect(generateDescriptionOnDemand(GUIDE_ID)).resolves.toEqual({ error: 'generation-failed' });
+ expect(updateGuideDescriptionMock).not.toHaveBeenCalled();
+ });
+
+ it('resolves to save-failed rather than rejecting when the write throws', async () => {
+ updateGuideDescriptionMock.mockRejectedValue(new Error('QuotaExceededError'));
+
+ await expect(generateDescriptionOnDemand(GUIDE_ID)).resolves.toEqual({ error: 'save-failed' });
+ });
+
+ it('resolves to save-failed rather than rejecting when reading the inputs throws', async () => {
+ localStorageGetMock.mockRejectedValue(new Error('DatabaseClosedError'));
+
+ await expect(generateDescriptionOnDemand(GUIDE_ID)).resolves.toEqual({ error: 'save-failed' });
+ });
+
+ it('stores and returns the description, leaving the title untouched', async () => {
+ await expect(generateDescriptionOnDemand(GUIDE_ID)).resolves.toEqual({
+ description: 'Generated description.',
+ });
+ expect(updateGuideDescriptionMock).toHaveBeenCalledWith(GUIDE_ID, 'Generated description.');
+ expect(updateGuideTitleMock).not.toHaveBeenCalled();
+ });
+ });
+});
diff --git a/src/entrypoints/background/guide-meta.ts b/src/entrypoints/background/guide-meta.ts
new file mode 100644
index 0000000..0b28902
--- /dev/null
+++ b/src/entrypoints/background/guide-meta.ts
@@ -0,0 +1,82 @@
+import { i18n } from '#imports';
+import { generateGuideMeta } from '@/core/capture/ai/meta';
+import { AI_PROVIDERS } from '@/core/capture/ai/models';
+import { getGuideDomain, getStepsForGuide, updateGuideDescription, updateGuideTitle } from '@/core/guides/service';
+import { localStorage } from '@/lib/browser-api';
+import { logger } from '@/lib/logger';
+import type { GenerateGuideDescriptionResponse, GuideDescriptionError } from '@/lib/messaging';
+
+type ResolveFailure = Extract<GuideDescriptionError, 'no-api-key' | 'no-steps'>;
+
+type GuideMetaInputs =
+ | { ok: true; steps: { description: string; url: string }[]; provider: string; model: string; apiKey: string }
+ | { ok: false; reason: ResolveFailure };
+
+async function resolveGuideMetaInputs(guideId: string): Promise<GuideMetaInputs> {
+ const settings = await localStorage.get(['aiApiKey', 'aiProvider', 'aiModel']);
+ if (!settings.aiApiKey) return { ok: false, reason: 'no-api-key' };
+
+ const steps = await getStepsForGuide(guideId);
+ const described = steps.filter((s) => s.description).map((s) => ({ description: s.description, url: s.url }));
+ if (described.length === 0) return { ok: false, reason: 'no-steps' };
+
+ const provider = (settings.aiProvider as string) || 'openai';
+ return {
+ ok: true,
+ steps: described.length > 15 ? [...described.slice(0, 10), ...described.slice(-5)] : described,
+ provider,
+ model: (settings.aiModel as string) || AI_PROVIDERS[provider].defaultModel,
+ apiKey: settings.aiApiKey as string,
+ };
+}
+
+async function applyFallbackTitle(guideId: string) {
+ const domain = await getGuideDomain(guideId);
+ await updateGuideTitle(
+ guideId,
+ domain ? i18n.t('background.guideOnDomain', [domain]) : i18n.t('background.newGuide'),
+ );
+}
+
+export async function generateGuideMetaOnStop(guideId: string) {
+ try {
+ const inputs = await resolveGuideMetaInputs(guideId);
+ if (!inputs.ok) {
+ if (inputs.reason === 'no-api-key') await applyFallbackTitle(guideId);
+ return;
+ }
+
+ const meta = await generateGuideMeta(inputs.steps, inputs.provider, inputs.model, inputs.apiKey);
+ if (!meta) {
+ await applyFallbackTitle(guideId);
+ return;
+ }
+
+ await updateGuideTitle(guideId, meta.title);
+ logger.info('Generated guide meta:', meta.title);
+ if (meta.description) {
+ await updateGuideDescription(guideId, meta.description).catch((err) =>
+ logger.error('Guide description write failed', err),
+ );
+ }
+ } catch (err) {
+ logger.error('Guide meta generation failed', err);
+ await applyFallbackTitle(guideId);
+ }
+}
+
+export async function generateDescriptionOnDemand(guideId: string): Promise<GenerateGuideDescriptionResponse> {
+ try {
+ const inputs = await resolveGuideMetaInputs(guideId);
+ if (!inputs.ok) return { error: inputs.reason };
+
+ const meta = await generateGuideMeta(inputs.steps, inputs.provider, inputs.model, inputs.apiKey);
+ if (!meta?.description) return { error: 'generation-failed' };
+
+ await updateGuideDescription(guideId, meta.description);
+ return { description: meta.description };
+ } catch (err) {
+ logger.error('On-demand description generation failed', err);
+ return { error: 'save-failed' };
+ }
+}
diff --git a/src/entrypoints/background/index.ts b/src/entrypoints/background/index.ts
index 7f18fe7..8849ff2 100644
--- a/src/entrypoints/background/index.ts
+++ b/src/entrypoints/background/index.ts
@@ -1,70 +1,25 @@
-import { browser, defineBackground, i18n } from '#imports';
-import { generateGuideMeta } from '@/core/capture/ai/meta';
+import { browser, defineBackground } from '#imports';
import { stepRequiresManual } from '@/core/guideme/manual';
import { advanceSession, cancelSession, completeSession, getSession, startSession } from '@/core/guideme/session';
-import {
- createGuide,
- getGuideDomain,
- getScreenshotsForSteps,
- getStepsForGuide,
- updateGuideDescription,
- updateGuideTitle,
-} from '@/core/guides/service';
+import { createGuide, getScreenshotsForSteps, getStepsForGuide } from '@/core/guides/service';
import type { Step } from '@/core/guides/types';
import { getActiveTab, localStorage, sendMessageToTab, setSidePanelBehavior, updateTab } from '@/lib/browser-api';
import { logger } from '@/lib/logger';
import { onMessage } from '@/lib/messaging';
import { broadcastStateToPanel, setupPortListener } from '@/lib/port';
import { getActor, getStateUpdate, initActor, initActorFallback, waitUntilReady } from './actor';
+import { generateDescriptionOnDemand, generateGuideMetaOnStop } from './guide-meta';
import { registerNavigationListeners } from './navigation';
import { handleCaptureStep, handleFinalizeInputStep, handleUpdateInputStep } from './step-pipeline';
import { broadcastStartCapture, broadcastStopCapture, showNotificationOnTab } from './tab-manager';
-async function applyFallbackTitle(guideId: string) {
- const domain = await getGuideDomain(guideId);
- await updateGuideTitle(
- guideId,
- domain ? i18n.t('background.guideOnDomain', [domain]) : i18n.t('background.newGuide'),
- );
-}
-
-async function generateGuideMetaInBackground(guideId: string) {
- try {
- const settings = await localStorage.get(['aiApiKey', 'aiProvider', 'aiModel']);
- if (!settings.aiApiKey) {
- await applyFallbackTitle(guideId);
- return;
- }
-
- const steps = await getStepsForGuide(guideId);
- const allSteps = steps.filter((s) => s.description).map((s) => ({ description: s.description, url: s.url }));
- if (allSteps.length === 0) return;
- const stepsWithUrl = allSteps.length > 15 ? [...allSteps.slice(0, 10), ...allSteps.slice(-5)] : allSteps;
-
- const provider = (settings.aiProvider as string) || 'openai';
- const model = (settings.aiModel as string) || 'gpt-4o-mini';
- const meta = await generateGuideMeta(stepsWithUrl, provider, model, settings.aiApiKey as string);
-
- if (!meta) {
- await applyFallbackTitle(guideId);
- return;
- }
-
- await updateGuideTitle(guideId, meta.title);
- if (meta.description) await updateGuideDescription(guideId, meta.description);
- logger.info('Generated guide meta:', meta.title);
- } catch (err) {
- logger.error('Guide meta generation failed', err);
- await applyFallbackTitle(guideId);
- }
-}
-
async function resolveManual(step: Step): Promise<boolean> {
if (!step.screenshotId) return stepRequiresManual(step, null);
const screenshots = await getScreenshotsForSteps([step.screenshotId]);
return stepRequiresManual(step, screenshots.get(step.id));
}
+
export default defineBackground(() => {
logger.info('Background service worker started');
@@ -148,7 +103,7 @@ export default defineBackground(() => {
await broadcastStopCapture();
actor.send({ type: 'STOP_RECORDING' });
- if (guideId) generateGuideMetaInBackground(guideId);
+ if (guideId) generateGuideMetaOnStop(guideId).catch(() => {});
return { success: true, guideId: guideId ?? undefined };
});
@@ -174,6 +129,8 @@ export default defineBackground(() => {
return { exited: true };
});
+ onMessage('generateGuideDescription', ({ data }) => generateDescriptionOnDemand(data.guideId));
+
onMessage('captureStep', async ({ data }) => {
await waitUntilReady();
return handleCaptureStep(data);
diff --git a/src/lib/messaging.ts b/src/lib/messaging.ts
index b2b3924..e0ca9c1 100644
--- a/src/lib/messaging.ts
+++ b/src/lib/messaging.ts
@@ -81,6 +81,17 @@ export interface GuideMe_GoToResponse {
moved: boolean;
}
+export type GuideDescriptionError = 'no-api-key' | 'no-steps' | 'generation-failed' | 'save-failed';
+
+export interface GenerateGuideDescriptionData {
+ guideId: string;
+}
+
+export interface GenerateGuideDescriptionResponse {
+ description?: string;
+ error?: GuideDescriptionError;
+}
+
export interface EnterBlurModeResponse {
entered: boolean;
}
@@ -102,6 +113,7 @@ interface MimikProtocol {
guideMeGoTo(data: GuideMe_GoToData): GuideMe_GoToResponse;
enterBlurMode(): EnterBlurModeResponse;
exitBlurMode(): ExitBlurModeResponse;
+ generateGuideDescription(data: GenerateGuideDescriptionData): GenerateGuideDescriptionResponse;
}
export const { sendMessage, onMessage } = defineExtensionMessaging<MimikProtocol>();