Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -610,10 +610,18 @@ firecrawl research related-papers pmcid:PMC12530322 --intent "in vivo delivery"

# Read full-text passages to verify a specific claim
firecrawl research read-paper doi:10.1016/j.neunet.2025.108095 --question "What was the sample size?"

# Curated location, function and GO terms for one protein, with cited paper ids
firecrawl research lookup-protein RPUSD3

# A gene symbol in another organism
firecrawl research lookup-protein Prkcb --organism "Mus musculus"
```

Paper ids accept `pmid:`, `pmcid:`, `doi:`, and `arxiv:` forms, plus canonical `paperId` values returned by search.

`lookup-protein` prints data from UniProtKB/Swiss-Prot, copyright [UniProt Consortium](https://www.uniprot.org), under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).

#### Subcommands

| Subcommand | Description |
Expand All @@ -622,6 +630,7 @@ Paper ids accept `pmid:`, `pmcid:`, `doi:`, and `arxiv:` forms, plus canonical `
| `inspect-paper <paperId>` | Canonical metadata: title, abstract, authors, categories, source ids, dates |
| `related-papers <seedIds...>` | Citation-graph expansion from seed papers, ranked against `--intent` |
| `read-paper <paperId>` | Best-matching in-body full-text passages for a `--question` |
| `lookup-protein <protein>` | Curated UniProt location, function and GO terms for one protein |

#### `search-papers` Options

Expand Down
290 changes: 289 additions & 1 deletion src/__tests__/commands/research.test.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { handleSearchPapersCommand } from '../../commands/research';
import {
handleLookupProteinCommand,
handleSearchPapersCommand,
} from '../../commands/research';
import { getClient } from '../../utils/client';
import { initializeConfig } from '../../utils/config';
import { writeOutput } from '../../utils/output';
Expand Down Expand Up @@ -116,3 +119,288 @@ describe('handleSearchPapersCommand', () => {
expectRenderedPapers();
});
});

describe('handleLookupProteinCommand', () => {
const found = {
success: true,
release: '2026_04',
match: 'found',
protein: {
accession: 'Q6P087',
entryName: 'RUSD3_HUMAN',
gene: 'RPUSD3',
synonyms: [],
name: 'Mitochondrial mRNA pseudouridine synthase RPUSD3',
organism: {
taxonId: 9606,
scientificName: 'Homo sapiens',
commonName: 'Human',
},
matchedBy: 'gene',
url: 'https://www.uniprot.org/uniprotkb/Q6P087/entry',
subcellularLocation: [
{
text: 'Mitochondrion matrix',
note: false,
evidence: [
{
kind: 'experimental',
eco: 'ECO:0000269',
paperId: 'pmid:27974379',
},
],
},
{
text: 'Localizes to mitochondrial RNA granules, platforms for post-transcriptional RNA modification and ribosome assembly',
note: true,
evidence: [
{
kind: 'experimental',
eco: 'ECO:0000269',
paperId: 'pmid:27974379',
},
{
kind: 'experimental',
eco: 'ECO:0000269',
paperId: 'pmid:28082677',
},
],
},
],
function: [
{
text: 'Catalyzes uridine to pseudouridine isomerization (pseudouridylation) of specific mitochondrial mRNAs (mt-mRNAs), a post-transcriptional modification necessary for their translation. Acts at position 390 in COXI mt-mRNA and at position 697-699 in mitochondrial COXIII mt-mRNA (PubMed:27974379). As a component of a functional protein-RNA module, consisting of RCC1L, NGRN, RPUSD3, RPUSD4, TRUB2, FASTKD2 and 16S mitochondrial ribosomal RNA (16S mt-rRNA), controls 16S mt-rRNA abundance and may play a role in mitochondrial ribosome biogenesis (PubMed:27667664)',
note: false,
evidence: [
{
kind: 'experimental',
eco: 'ECO:0000269',
paperId: 'pmid:27667664',
},
{
kind: 'experimental',
eco: 'ECO:0000269',
paperId: 'pmid:27974379',
},
],
},
],
goCellularComponent: [
{
id: 'GO:0005759',
term: 'mitochondrial matrix',
code: 'IDA',
assignedBy: 'FlyBase',
paperIds: ['pmid:27974379'],
},
{
id: 'GO:0005739',
term: 'mitochondrion',
code: 'IDA',
assignedBy: 'FlyBase',
paperIds: ['pmid:28082677'],
},
{
id: 'GO:0035770',
term: 'ribonucleoprotein granule',
code: 'IDA',
assignedBy: 'FlyBase',
paperIds: ['pmid:28082677'],
},
],
paperIds: ['pmid:27974379', 'pmid:28082677', 'pmid:27667664'],
},
notice:
'Protein data from UniProtKB/Swiss-Prot release 2026_04. Copyright UniProt Consortium, https://www.uniprot.org. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/. No warranty, see https://www.uniprot.org/help/license. Selected fields, reformatted.',
};

beforeEach(() => {
setupTest();
});

afterEach(() => {
teardownTest();
vi.clearAllMocks();

@cubic-dev-ai cubic-dev-ai Bot Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: vi.clearAllMocks() does not restore the console.error and process.exit spies these tests install, so they stay mocked for the rest of the file. Use vi.restoreAllMocks() in this afterEach, as the other test files do.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At src/__tests__/commands/research.test.ts, line 223:

<comment>`vi.clearAllMocks()` does not restore the `console.error` and `process.exit` spies these tests install, so they stay mocked for the rest of the file. Use `vi.restoreAllMocks()` in this afterEach, as the other test files do.</comment>

<file context>
@@ -116,3 +119,288 @@ describe('handleSearchPapersCommand', () => {
+
+  afterEach(() => {
+    teardownTest();
+    vi.clearAllMocks();
+    vi.unstubAllEnvs();
+    vi.unstubAllGlobals();
</file context>
Suggested change
vi.clearAllMocks();
vi.restoreAllMocks();
Fix with cubic

vi.unstubAllEnvs();
vi.unstubAllGlobals();
});

it('sends protein and organism and prints the found entry with an API key', async () => {
initializeConfig({
apiKey: 'test-api-key',
apiUrl: 'https://api.firecrawl.dev',
});
const mockHttpGet = vi.fn().mockResolvedValue({ data: found });
vi.mocked(getClient).mockReturnValue({
http: { get: mockHttpGet },
} as any);

await handleLookupProteinCommand({
protein: 'RPUSD3',
organism: 'Homo sapiens',
});

expect(mockHttpGet).toHaveBeenCalledWith(
'/v2/search/research/proteins?protein=RPUSD3&organism=Homo+sapiens&integration=cli&origin=cli.test%401.0.0'
);
expect(vi.mocked(writeOutput).mock.calls[0][0]).toBe(
[
'# RPUSD3 (Q6P087, RUSD3_HUMAN), Homo sapiens',
'Mitochondrial mRNA pseudouridine synthase RPUSD3. Matched by gene symbol.',
'',
'Subcellular location',
'- Mitochondrion matrix. Experimental [pmid:27974379]',
'- Note: Localizes to mitochondrial RNA granules, platforms for post-transcriptional RNA modification and ribosome assembly. Experimental [pmid:27974379, pmid:28082677]',
'GO cellular component (experimental)',
'- mitochondrial matrix (GO:0005759), IDA, FlyBase [pmid:27974379]',
'- mitochondrion (GO:0005739), IDA, FlyBase [pmid:28082677]',
'- ribonucleoprotein granule (GO:0035770), IDA, FlyBase [pmid:28082677]',
'Function',
`- ${found.protein.function[0].text}. Experimental [pmid:27667664, pmid:27974379]`,
'Open a cited paper with `firecrawl research inspect-paper <paperId>` or `firecrawl research read-paper <paperId> --question <question>`.',
`Source: https://www.uniprot.org/uniprotkb/Q6P087/entry. ${found.notice}`,
].join('\n')
);
});

it('lists candidates for an ambiguous protein without an API key', async () => {
vi.stubEnv('FIRECRAWL_API_KEY', '');
initializeConfig({ apiUrl: 'https://api.firecrawl.dev' });
const ambiguous = {
success: true,
release: '2026_04',
match: 'ambiguous',
candidates: [
{
accession: 'P05771',
entryName: 'KPCB_HUMAN',
gene: 'PRKCB',
name: 'Protein kinase C beta type',
organism: { taxonId: 9606, scientificName: 'Homo sapiens' },
matchedBy: 'name',
},
],
candidateCount: 12,
notice: found.notice,
};
const fetchMock = vi.fn(
async (_url: string, _init?: RequestInit) =>
new Response(JSON.stringify(ambiguous), { status: 200 })
);
vi.stubGlobal('fetch', fetchMock);

await handleLookupProteinCommand({ protein: 'kinase' });

expect(getClient).not.toHaveBeenCalled();
expect(fetchMock).toHaveBeenCalledWith(
'https://api.firecrawl.dev/v2/search/research/proteins?protein=kinase&integration=cli&origin=cli.test%401.0.0',
expect.objectContaining({ method: 'GET' })
);
expect(vi.mocked(writeOutput).mock.calls[0][0]).toBe(
[
'"kinase" does not resolve to one UniProtKB/Swiss-Prot entry in the requested organism (human unless --organism is set). 12 candidates, the first 1 listed, as accession, entry name, gene, name, organism:',
'- P05771, KPCB_HUMAN, PRKCB, Protein kinase C beta type, Homo sapiens',
'Run `firecrawl research lookup-protein` again with one accession.',
found.notice,
].join('\n')
);
});

it('says what to pass and names search-papers when no entry matches', async () => {
initializeConfig({
apiKey: 'test-api-key',
apiUrl: 'https://api.firecrawl.dev',
});
vi.mocked(getClient).mockReturnValue({
http: {
get: vi.fn().mockResolvedValue({
data: {
success: true,
release: '2026_04',
match: 'not_found',
notice: found.notice,
},
}),
},
} as any);

await handleLookupProteinCommand({ protein: 'where is RPUSD3 localized' });

expect(vi.mocked(writeOutput).mock.calls[0][0]).toBe(
'No UniProtKB/Swiss-Prot entry matches "where is RPUSD3 localized". Pass a UniProt accession (P05771), an entry name (KPCB_HUMAN), or a gene symbol with --organism. Only reviewed entries are covered. For a free-text question, use `firecrawl research search-papers`.'
);
});

it('fails on a body that is not a lookup result instead of saying no entry matches', async () => {
initializeConfig({
apiKey: 'test-api-key',
apiUrl: 'https://api.firecrawl.dev',
});
const consoleError = vi
.spyOn(console, 'error')
.mockImplementation(() => {});
const exit = vi
.spyOn(process, 'exit')
.mockImplementation(() => undefined as never);

for (const body of [
{
success: true,
release: '2026_04',
match: 'partial',
notice: found.notice,
},
{},
]) {
vi.mocked(getClient).mockReturnValue({
http: { get: vi.fn().mockResolvedValue({ data: body }) },
} as any);

await handleLookupProteinCommand({ protein: 'RPUSD3' });
}

expect(consoleError.mock.calls).toEqual([
[
'Error:',
'The protein lookup returned an unexpected response (match: "partial").',
],
[
'Error:',
'The protein lookup returned an unexpected response (match: undefined).',
],
]);
expect(exit.mock.calls).toEqual([[1], [1]]);
expect(writeOutput).not.toHaveBeenCalled();
});

it('prints the API error for a refused organism with an API key', async () => {
initializeConfig({
apiKey: 'test-api-key',
apiUrl: 'https://api.firecrawl.dev',
});
const error =
"unknown organism 'Martian': pass an NCBI taxon ID such as 9606, a scientific name such as Homo sapiens, or a UniProt common name such as Human";
vi.mocked(getClient).mockReturnValue({
http: {
get: vi.fn().mockRejectedValue({
response: { status: 400, data: { success: false, error } },
}),
},
} as any);
const consoleError = vi
.spyOn(console, 'error')
.mockImplementation(() => {});
const exit = vi
.spyOn(process, 'exit')
.mockImplementation(() => undefined as never);

await handleLookupProteinCommand({
protein: 'RPUSD3',
organism: 'Martian',
});

expect(consoleError).toHaveBeenCalledWith('Error:', error);
expect(exit).toHaveBeenCalledWith(1);
expect(writeOutput).not.toHaveBeenCalled();
});
});
15 changes: 7 additions & 8 deletions src/commands/gov.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,9 @@
import { getClient, isKeylessMode, keylessGet } from '../utils/client';
import {
getClient,
isKeylessMode,
keyedGet,
keylessGet,
} from '../utils/client';
import { getCliOrigin } from '../utils/agent-origin';
import { writeOutput } from '../utils/output';
import type {
Expand All @@ -24,13 +29,7 @@ async function getGov<T>(path: string, options: GovSearchOptions): Promise<T> {
}

const app = getClient({ apiKey: options.apiKey, apiUrl: options.apiUrl });
try {
const response = await (app as any).http.get(url);
return (response?.data ?? {}) as T;
} catch (error: any) {
const message = error?.response?.data?.error;
throw typeof message === 'string' ? new Error(message) : error;
}
return (await keyedGet(app, url)) as T;
}

function fmtResult(item: GovResult, index: number): string {
Expand Down
Loading
Loading