diff --git a/apps/api/prisma/schema.prisma b/apps/api/prisma/schema.prisma
index 9fcfa44f0..fa8598208 100644
--- a/apps/api/prisma/schema.prisma
+++ b/apps/api/prisma/schema.prisma
@@ -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?
diff --git a/apps/api/src/instrument-repos/__tests__/instrument-repos.service.test.ts b/apps/api/src/instrument-repos/__tests__/instrument-repos.service.test.ts
index b0225f2e9..0789f4a44 100644
--- a/apps/api/src/instrument-repos/__tests__/instrument-repos.service.test.ts
+++ b/apps/api/src/instrument-repos/__tests__/instrument-repos.service.test.ts
@@ -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',
@@ -269,6 +270,7 @@ describe('InstrumentReposService', () => {
expect(instrumentRepoSyncLogModel.create.mock.lastCall?.[0].data).toStrictEqual({
action: 'IMPORT',
+ createdCount: 0,
failures,
importedCount: 1,
message: null,
@@ -517,6 +519,7 @@ describe('InstrumentReposService', () => {
it.each([
['action', [{ action: 'asc' }]],
+ ['createdCount', [{ createdCount: 'asc' }]],
['failedCount', [{ failures: { _count: 'asc' } }]],
['importedCount', [{ importedCount: 'asc' }]],
['repoName', [{ repoName: 'asc' }]],
@@ -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 });
@@ -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 });
@@ -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 });
@@ -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')));
diff --git a/apps/api/src/instrument-repos/instrument-repos.service.ts b/apps/api/src/instrument-repos/instrument-repos.service.ts
index c8364c6ff..b356e22af 100644
--- a/apps/api/src/instrument-repos/instrument-repos.service.ts
+++ b/apps/api/src/instrument-repos/instrument-repos.service.ts
@@ -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 }],
@@ -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()
@@ -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: {
@@ -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();
@@ -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;
@@ -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[] = [];
@@ -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 } });
}
@@ -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 };
diff --git a/apps/api/test/suites/06-instrument-repo-readd.suite.ts b/apps/api/test/suites/06-instrument-repo-readd.suite.ts
index 408d21932..56aceb112 100644
--- a/apps/api/test/suites/06-instrument-repo-readd.suite.ts
+++ b/apps/api/test/suites/06-instrument-repo-readd.suite.ts
@@ -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/')
@@ -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);
@@ -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);
diff --git a/apps/web/src/components/InstrumentRepoSyncLogTable/InstrumentRepoSyncLogTable.tsx b/apps/web/src/components/InstrumentRepoSyncLogTable/InstrumentRepoSyncLogTable.tsx
index 9cf11621a..dc4e49356 100644
--- a/apps/web/src/components/InstrumentRepoSyncLogTable/InstrumentRepoSyncLogTable.tsx
+++ b/apps/web/src/components/InstrumentRepoSyncLogTable/InstrumentRepoSyncLogTable.tsx
@@ -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()}`;
@@ -161,13 +190,13 @@ const InstrumentRepoSyncLogTable = ({
/>
),
id: 'status',
- size: 140
+ size: 124
},
{
accessorKey: 'importedCount',
cell: (ctx) => {
- const count = String(ctx.row.original.importedCount);
- return