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
1 change: 1 addition & 0 deletions apps/api/prisma/schema.prisma
Original file line number Diff line number Diff line change
Expand Up @@ -281,6 +281,7 @@ model InstrumentRepoSyncLog {
updatedAt DateTime @updatedAt @db.Date
id String @id @default(auto()) @map("_id") @db.ObjectId
action InstrumentRepoSyncAction
createdCount Int?
failures InstrumentRepoSyncFailure[]
importedCount Int
message String?
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -251,6 +251,7 @@ describe('InstrumentReposService', () => {
expect(instrumentRepoModel.create).not.toHaveBeenCalled();
expect(instrumentRepoSyncLogModel.create.mock.lastCall?.[0].data).toStrictEqual({
action: 'IMPORT',
createdCount: 0,
failures: [],
importedCount: 0,
message: 'Repository not found',
Expand All @@ -269,6 +270,7 @@ describe('InstrumentReposService', () => {

expect(instrumentRepoSyncLogModel.create.mock.lastCall?.[0].data).toStrictEqual({
action: 'IMPORT',
createdCount: 0,
failures,
importedCount: 1,
message: null,
Expand Down Expand Up @@ -517,6 +519,7 @@ describe('InstrumentReposService', () => {

it.each([
['action', [{ action: 'asc' }]],
['createdCount', [{ createdCount: 'asc' }]],
['failedCount', [{ failures: { _count: 'asc' } }]],
['importedCount', [{ importedCount: 'asc' }]],
['repoName', [{ repoName: 'asc' }]],
Expand Down Expand Up @@ -763,7 +766,7 @@ describe('InstrumentReposService', () => {
});

it('should request the main branch zipball from the GitHub API with the repo token', async () => {
fetchMock.mockResolvedValueOnce(await zipball({}));
fetchMock.mockResolvedValueOnce(await zipball(instrumentFiles('forms', 'A')));

await service.create({ accessToken: 'repo-token', url });

Expand All @@ -773,7 +776,7 @@ describe('InstrumentReposService', () => {

it('should fall back to the server-wide token when the repo has none', async () => {
configService.get.mockReturnValue('server-token');
fetchMock.mockResolvedValueOnce(await zipball({}));
fetchMock.mockResolvedValueOnce(await zipball(instrumentFiles('forms', 'A')));

await service.create({ url });

Expand All @@ -782,7 +785,7 @@ describe('InstrumentReposService', () => {
});

it('should send no authorization header when no token is configured', async () => {
fetchMock.mockResolvedValueOnce(await zipball({}));
fetchMock.mockResolvedValueOnce(await zipball(instrumentFiles('forms', 'A')));

await service.create({ url });

Expand Down Expand Up @@ -882,6 +885,94 @@ describe('InstrumentReposService', () => {
expect(instrumentModel.update).not.toHaveBeenCalled();
});

it('should refuse a repository that provides no instrument directories, rather than import nothing', async () => {
fetchMock.mockResolvedValueOnce(await zipball({ 'public/forms/A/index.ts': "export default 'A';" }));

await expect(service.create({ url })).rejects.toThrow(
'Found no instruments in owner/repo. An instrument is a directory holding an index.ts, index.tsx, index.js or index.jsx file, within lib/file, lib/forms, lib/interactive, lib/series at the root of the repository.'
);
expect(instrumentRepoModel.create).not.toHaveBeenCalled();
});

it('should log an empty repository as a failure, so it is not indistinguishable from a clean import', async () => {
fetchMock.mockResolvedValueOnce(await zipball({ 'README.md': '# repo' }));

await expect(service.create({ url })).rejects.toThrow('Found no instruments in owner/repo');

expect(instrumentRepoSyncLogModel.create.mock.lastCall?.[0].data).toMatchObject({
createdCount: 0,
failures: [],
importedCount: 0,
message: expect.stringContaining('Found no instruments in owner/repo')
});
});

// The refusal runs on a sync too, where returning before the update is what keeps a repository's
// instruments listed: replacing the id list with nothing would de-list every one of them.
it('should keep the instruments a registered repository provides when a sync finds none', async () => {
instrumentRepoModel.findFirst.mockResolvedValueOnce({
accessToken: null,
id: 'r1',
instrumentIds: ['stored'],
name: 'repo',
owner: 'owner',
repoName: 'repo'
});
fetchMock.mockResolvedValueOnce(await zipball({ 'README.md': '# repo' }));

await expect(service.sync('r1')).rejects.toThrow('Found no instruments in owner/repo');

expect(instrumentRepoModel.update).not.toHaveBeenCalled();
expect(instrumentRepoSyncLogModel.create.mock.lastCall?.[0].data).toMatchObject({
action: 'SYNC',
createdCount: 0,
importedCount: 0,
message: expect.stringContaining('Found no instruments in owner/repo'),
repoId: 'r1'
});
});

// A readable repository whose every instrument fails is not a repository that provides none, so the
// stored list stands rather than being replaced with nothing.
it('should keep the stored instrument list when a sync matches none of what it found', async () => {
instrumentRepoModel.findFirst.mockResolvedValueOnce({
accessToken: null,
id: 'r1',
instrumentIds: ['stored'],
name: 'repo',
owner: 'owner',
repoName: 'repo'
});
fetchMock.mockResolvedValueOnce(await zipball(instrumentFiles('forms', 'A')));
instrumentsService.create.mockRejectedValueOnce(new UnprocessableEntityException('details.title: Required'));

await service.sync('r1');

expect(instrumentRepoModel.update).not.toHaveBeenCalled();
expect(instrumentRepoSyncLogModel.create.mock.lastCall?.[0].data).toMatchObject({
createdCount: 0,
importedCount: 0,
message: null
});
expect(instrumentRepoSyncLogModel.create.mock.lastCall?.[0].data.failures).toHaveLength(1);
});

it('should count only the instruments it stored as created, so ones already present are not reported as new', async () => {
fetchMock.mockResolvedValueOnce(
await zipball({ ...instrumentFiles('forms', 'A'), ...instrumentFiles('forms', 'B') })
);
instrumentsService.create
.mockResolvedValueOnce({ id: 'created' })
.mockRejectedValueOnce(new ConflictException("Instrument with ID 'existing' already exists!"));

await service.create({ url });

expect(instrumentRepoSyncLogModel.create.mock.lastCall?.[0].data).toMatchObject({
createdCount: 1,
importedCount: 2
});
});

it('should record a conflict that does not name the existing instrument as a failure', async () => {
const message = 'An instrument with the same title already exists';
fetchMock.mockResolvedValueOnce(await zipball(instrumentFiles('forms', 'A')));
Expand Down
71 changes: 44 additions & 27 deletions apps/api/src/instrument-repos/instrument-repos.service.ts
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ const getSyncLogOrderBy = (
const orderBy = {
action: [{ action: sortOrder }],
createdAt: [{ createdAt: sortOrder }],
createdCount: [{ createdCount: sortOrder }],
failedCount: [{ failures: { _count: sortOrder } }],
importedCount: [{ importedCount: sortOrder }],
repoName: [{ repoName: sortOrder }],
Expand All @@ -64,6 +65,15 @@ const getSyncLogOrderBy = (
return [...orderBy, { id: 'desc' as const }];
};

/**
* The directories a repository may provide instruments in, relative to its root. `series` is scanned
* last, and callers must import in that order: a series is rejected unless every instrument it
* references is already stored, so the scalars a repo provides have to be created first. A series
* referencing a *different* repo still fails; see
* `.agents/docs/architecture/instrument-pipeline.md`.
*/
const INSTRUMENT_CATEGORIES = ['file', 'forms', 'interactive', 'series'] as const;

const $ExceptionDetails = z.object({
cause: z.object({ message: z.string() }).optional(),
issues: z.array(z.object({ message: z.string(), path: z.array(z.union([z.string(), z.number()])) })).optional()
Expand Down Expand Up @@ -131,7 +141,7 @@ export class InstrumentReposService implements OnModuleInit {
await this.recordSync({ action: 'IMPORT', error: err, repoId: null, repoName });
throw err;
}
const { createdIds, failures, instrumentIds } = result;
const { createdIds, instrumentIds } = result;

const repo = await this.instrumentRepoModel.create({
data: {
Expand All @@ -148,13 +158,7 @@ export class InstrumentReposService implements OnModuleInit {
// Attribute provenance only to instruments this import actually created. Instruments that
// already existed (e.g. added manually) keep their original provenance.
await this.tagInstruments(createdIds, repo.id, repo.name);
await this.recordSync({
action: 'IMPORT',
failures,
importedCount: instrumentIds.length,
repoId: repo.id,
repoName
});
await this.recordSync({ action: 'IMPORT', repoId: repo.id, repoName, result });
// Re-adopt any pre-existing instruments orphaned by a previously-deleted copy of this repo.
await this.reconcileOrphanedInstruments();

Expand Down Expand Up @@ -294,11 +298,7 @@ export class InstrumentReposService implements OnModuleInit {

private discoverInstrumentDirs(repoDir: string): string[] {
const dirs: string[] = [];
// `series` is scanned last, and callers must import in the returned order: a series is rejected
// unless every instrument it references is already stored, so the scalars a repo provides have to
// be created first. A series referencing a *different* repo still fails; see
// `.agents/docs/architecture/instrument-pipeline.md`.
for (const category of ['file', 'forms', 'interactive', 'series']) {
for (const category of INSTRUMENT_CATEGORIES) {
const libDir = path.join(repoDir, 'lib', category);
if (!fs.existsSync(libDir)) {
continue;
Expand Down Expand Up @@ -453,6 +453,15 @@ export class InstrumentReposService implements OnModuleInit {
const instrumentDirs = this.discoverInstrumentDirs(repoDir);
this.loggingService.log(`Found ${instrumentDirs.length} instrument directories in ${owner}/${repoName}`);

// Importing nothing is a failure, not an empty success: a repository laid out any other way
// downloads cleanly and yields no directories, and a log reading "0 imported" with nothing wrong
// gives no way to tell that apart from a repository that is genuinely empty.
if (instrumentDirs.length === 0) {
throw new BadGatewayException(
`Found no instruments in ${owner}/${repoName}. An instrument is a directory holding an index.ts, index.tsx, index.js or index.jsx file, within ${INSTRUMENT_CATEGORIES.map((category) => `lib/${category}`).join(', ')} at the root of the repository.`
);
}

// instrumentIds: every instrument the repo provides; createdIds: only those newly created here.
const instrumentIds: string[] = [];
const createdIds: string[] = [];
Expand Down Expand Up @@ -581,14 +590,21 @@ export class InstrumentReposService implements OnModuleInit {

private recordSync(
entry: { action: InstrumentRepoSyncAction; repoId: null | string; repoName: string } & (
{ error: unknown } | { failures: InstrumentRepoSyncFailure[]; importedCount: number }
{ error: unknown } | { result: RepoImportResult }
)
) {
const { action, repoId, repoName } = entry;
// Counted off the import result rather than passed in beside it, so the entry cannot disagree
// with what the import actually did.
const outcome =
'error' in entry
? { failures: [], importedCount: 0, message: describeImportError(entry.error) }
: { failures: entry.failures, importedCount: entry.importedCount, message: null };
? { createdCount: 0, failures: [], importedCount: 0, message: describeImportError(entry.error) }
: {
createdCount: entry.result.createdIds.length,
failures: entry.result.failures,
importedCount: entry.result.instrumentIds.length,
message: null
};
return this.instrumentRepoSyncLogModel.create({ data: { action, repoId, repoName, ...outcome } });
}

Expand All @@ -613,17 +629,18 @@ export class InstrumentReposService implements OnModuleInit {

// Replaced rather than merged, so the list is what the repository provides now. An edition dropped
// here stays in the database with its provenance tag, so groups can still see and administer it.
const updated = await this.instrumentRepoModel.update({
data: { instrumentIds: result.instrumentIds, lastSyncedAt: new Date() },
where: { id: repo.id }
});
const log = await this.recordSync({
action: 'SYNC',
failures: result.failures,
importedCount: result.instrumentIds.length,
repoId: repo.id,
repoName: repo.name
});
//
// A pass that matched nothing is left out of that replacement. Every instrument failing to load —
// a bad upstream commit, a series whose member edition is gone — is not evidence that the
// repository provides nothing, and writing an empty list would de-list instruments that are still
// stored and still assignable. The entry records the failures, so the pass is reported, not hidden.
const updated = result.instrumentIds.length
? await this.instrumentRepoModel.update({
data: { instrumentIds: result.instrumentIds, lastSyncedAt: new Date() },
where: { id: repo.id }
})
: repo;
const log = await this.recordSync({ action: 'SYNC', repoId: repo.id, repoName: repo.name, result });
// Re-adopt any instruments that were orphaned by a previously-deleted copy of this repo.
await this.reconcileOrphanedInstruments();
return { log, ok: true as const, repo: updated };
Expand Down
21 changes: 16 additions & 5 deletions apps/api/test/suites/06-instrument-repo-readd.suite.ts
Original file line number Diff line number Diff line change
Expand Up @@ -89,9 +89,20 @@ export default defineSuite('re-adding a registered instrument repository', funct
return (await prisma().instrumentRepo.findUniqueOrThrow({ where: { id } })).accessToken;
};

/** Answers every GitHub download with an empty repository, and passes any other request on. */
const stubGitHub = async () => {
const archive = await new JSZip().generateAsync({ type: 'arraybuffer' });
/**
* Answers every GitHub download with a repository, and passes any other request on.
*
* `providesInstrument` adds one instrument directory, which a sync that is expected to succeed
* needs: a repository providing none is refused outright. Its contents do not matter, since an
* instrument that fails to load is recorded against the sync rather than refused. The tests that
* expect a refusal leave it off, so they pay nothing for bundling an instrument no one reads.
*/
const stubGitHub = async ({ providesInstrument = false }: { providesInstrument?: boolean } = {}) => {
const zip = new JSZip();
if (providesInstrument) {
zip.file('repo/lib/forms/example/index.ts', "export default 'example';");
}
const archive = await zip.generateAsync({ type: 'arraybuffer' });
const realFetch = globalThis.fetch;
const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation((input, init) => {
return typeof input === 'string' && input.startsWith('https://api.github.com/')
Expand Down Expand Up @@ -158,7 +169,7 @@ export default defineSuite('re-adding a registered instrument repository', funct
{ action: 'update', groupId: ownGroup.id, subject: 'InstrumentRepo' }
]);
const repo = await registerRepo('own-group-target', [ownGroup.id]);
const fetchSpy = await stubGitHub();
const fetchSpy = await stubGitHub({ providesInstrument: true });

const response = await reAdd(headers, repo.url);

Expand All @@ -168,7 +179,7 @@ export default defineSuite('re-adding a registered instrument repository', funct

it('should let an administrator replace the token and re-sync, which is how an expired one is refreshed', async () => {
const repo = await registerRepo('admin-target', [otherGroup.id]);
const fetchSpy = await stubGitHub();
const fetchSpy = await stubGitHub({ providesInstrument: true });

const response = await reAdd(adminHeaders, repo.url);

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,35 @@ const InstrumentRepoSyncLogTable = ({
LOAD: t({ en: 'Load', es: 'Carga', fr: 'Chargement' })
} satisfies { [K in InstrumentRepoSyncStage]: string };

/**
* `importedCount` is every instrument the repository provided; `createdCount` is how many of those
* this run stored for the first time, so the remainder were already in the database. The split rides
* in this one column because the table is already as wide as the page lets it be — two more columns
* would take their room from the repository name, whose header cannot truncate.
*
* An entry that imported nothing reads as the bare total: a run that was refused outright, or whose
* every instrument failed, records a `createdCount` of zero, and `0 (0 new)` would dress a row that
* stored nothing as a split it does not have.
*/
const describeImported = ({ createdCount, importedCount }: InstrumentRepoSyncLog) => {
if (createdCount === null || createdCount === undefined || importedCount === 0) {
return { title: String(importedCount), value: String(importedCount) };
}
const existingCount = importedCount - createdCount;
return {
title: t({
en: `${importedCount} imported: ${createdCount} new, ${existingCount} already stored`,
es: `${importedCount} importados: ${createdCount} nuevos, ${existingCount} ya almacenados`,
fr: `${importedCount} importés : ${createdCount} nouveaux, ${existingCount} déjà stockés`
}),
value: t({
en: `${importedCount} (${createdCount} new)`,
es: `${importedCount} (${createdCount} nuevos)`,
fr: `${importedCount} (${createdCount} nouv.)`
})
};
};

/** Which import or sync the dialog is showing, since the dialog is detached from its row. */
const describeLog = (log: InstrumentRepoSyncLog) =>
`${log.repoName} · ${actionLabels[log.action]} · ${log.createdAt.toLocaleString()}`;
Expand Down Expand Up @@ -161,13 +190,13 @@ const InstrumentRepoSyncLogTable = ({
/>
),
id: 'status',
size: 140
size: 124
},
{
accessorKey: 'importedCount',
cell: (ctx) => {
const count = String(ctx.row.original.importedCount);
return <TruncatedCell title={count} value={count} />;
const { title, value } = describeImported(ctx.row.original);
return <TruncatedCell title={title} value={value} />;
},
header: ({ column }) => (
<SortableHeader
Expand All @@ -176,7 +205,7 @@ const InstrumentRepoSyncLogTable = ({
sortOrder={sortOrderOf('importedCount')}
/>
),
size: 114
size: 130
},
{
accessorFn: (log) => log.failures.length,
Expand Down
Loading
Loading