Skip to content

Commit 97f50f5

Browse files
committed
fix(spec): PackageInstallResponseSchema declares the bare installed row the install door serves
POST /api/v1/packages answers success(pkg): the InstalledPackage row as data. The published contract declared data: { package, dependencyResolution?, namespaceConflicts?, message? }, a wrapper no surface sends. The contract now follows the wire; a contract-vs-wire pin in the client harness drives the real dispatcher and parses its answer with PackageApiContracts.installPackage.output. Claude-Session: https://claude.ai/code/session_01WGufzgC3iduZ3nT4eSzSkT Co-authored-by: Claude <noreply@anthropic.com>
1 parent f6faf75 commit 97f50f5

3 files changed

Lines changed: 112 additions & 56 deletions

File tree

‎packages/client/src/packages-write-envelope.test.ts‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,9 @@ import { tmpdir } from 'node:os';
6868
import { join } from 'node:path';
6969
import { SchemaRegistry } from '@objectstack/objectql';
7070
import { HttpDispatcher } from '@objectstack/runtime';
71+
// The route map ships from `/api-assembled` (its read responses embed the
72+
// assembled package body); the install output it binds is declared in `/api`.
73+
import { PackageApiContracts } from '@objectstack/spec/api-assembled';
7174
import { ObjectStackClient } from './index';
7275

7376
const BASE_URL = 'http://localhost:3000';
@@ -232,3 +235,58 @@ describe('#12034 — the packages write verbs answer the bare row, not `{ packag
232235
expect(await client.packages.enable(MANIFEST.id)).toEqual(body.data);
233236
});
234237
});
238+
239+
/**
240+
* [#30464] The published contract for `POST /api/v1/packages`, held against
241+
* what the door really answers.
242+
*
243+
* The half above pins the CLIENT's declaration to the wire. This half pins the
244+
* SPEC's: `PackageApiContracts.installPackage.output` is what an integrator
245+
* generates a client from, and it declared `data: { package, … }` — a wrapper
246+
* no surface sends, so code written against it read `data.package` and got
247+
* `undefined`. The contract now follows the wire (the door was not changed).
248+
*
249+
* Same in-process chain as above: a real `SchemaRegistry`, the real
250+
* `HttpDispatcher` answering it, and the dispatcher's own body handed to the
251+
* declared schema untouched. Nothing here writes the expected body out by
252+
* hand, which is how the false declaration survived in the first place.
253+
*/
254+
describe('#30464 — PackageApiContracts.installPackage.output parses the install door\'s real answer', () => {
255+
async function installThroughTheDoor() {
256+
const registry = new SchemaRegistry();
257+
const { dispatcher } = dispatcherBackedClient(registry);
258+
const raw = await dispatcher.handlePackages('', 'POST', { manifest: MANIFEST }, {}, CONTEXT());
259+
return { registry, status: raw.response?.status, body: raw.response?.body as any };
260+
}
261+
262+
it('the door\'s 201 body parses green, and the parse keeps every key the door sent', async () => {
263+
const { registry, status, body } = await installThroughTheDoor();
264+
expect(status).toBe(201);
265+
266+
const parsed = PackageApiContracts.installPackage.output.safeParse(body);
267+
expect(parsed.success, JSON.stringify(parsed.error?.issues)).toBe(true);
268+
269+
// The declared `data` IS the row the registry recorded — nothing the
270+
// door sent was stripped by the parse, and nothing was invented by it.
271+
expect(parsed.data!.data).toEqual(body.data);
272+
expect(parsed.data!.data).toEqual(registry.getPackage(MANIFEST.id));
273+
expect(parsed.data!.data.manifest.id).toBe(MANIFEST.id);
274+
});
275+
276+
it('the old `{ package }` reading is refused by the contract, and absent from the wire', async () => {
277+
const { body } = await installThroughTheDoor();
278+
279+
expect('package' in body.data).toBe(false);
280+
expect('message' in body.data).toBe(false);
281+
282+
// The wrapper the contract used to promise, built from the door's own
283+
// row, no longer passes it: the declaration and the wire cannot both
284+
// be read as true.
285+
const wrapped = { ...body, data: { package: body.data } };
286+
const parsed = PackageApiContracts.installPackage.output.safeParse(wrapped);
287+
expect(parsed.success).toBe(false);
288+
expect(parsed.error!.issues.map((i) => i.path.join('.'))).toEqual(
289+
expect.arrayContaining(['data.manifest', 'data.source']),
290+
);
291+
});
292+
});

‎packages/spec/src/api/package-api.test.ts‎

Lines changed: 27 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -201,53 +201,38 @@ describe('PackageInstallRequestSchema', () => {
201201
});
202202

203203
describe('PackageInstallResponseSchema', () => {
204-
it('should accept a successful install response', () => {
205-
const result = PackageInstallResponseSchema.parse({
206-
success: true,
207-
data: {
208-
package: {
209-
manifest: { id: 'com.acme.crm', name: 'acme_crm', version: '1.0.0', type: 'plugin' },
210-
source: 'authored',
211-
status: 'installed',
212-
enabled: true,
213-
},
214-
dependencyResolution: {
215-
dependencies: [
216-
{ packageId: 'com.acme.core', requiredRange: '^1.0.0', status: 'satisfied', resolvedVersion: '1.2.0' },
217-
],
218-
canProceed: true,
219-
requiredActions: [],
220-
installOrder: ['com.acme.core', 'com.acme.crm'],
221-
},
222-
message: 'Package installed successfully',
223-
},
224-
});
204+
// The row `POST /api/v1/packages` answers as `data` — bare, no wrapper. The
205+
// wire half (the real dispatcher's answer parsed with this schema) is pinned
206+
// in `packages/client/src/packages-write-envelope.test.ts`.
207+
const ROW = {
208+
manifest: { id: 'com.acme.crm', name: 'acme_crm', version: '1.0.0', type: 'plugin' },
209+
source: 'authored',
210+
status: 'installed',
211+
enabled: true,
212+
installedAt: '2026-11-05T00:00:00.000Z',
213+
};
214+
215+
it('accepts the installed row itself as data', () => {
216+
const result = PackageInstallResponseSchema.parse({ success: true, data: ROW });
225217
expect(result.success).toBe(true);
226-
expect(result.data.package.status).toBe('installed');
227-
expect(result.data.dependencyResolution?.canProceed).toBe(true);
218+
expect(result.data.manifest.id).toBe('com.acme.crm');
219+
expect(result.data.source).toBe('authored');
220+
expect(result.data.status).toBe('installed');
221+
expect(result.data.enabled).toBe(true);
228222
});
229223

230-
it('should accept install response with namespace conflicts', () => {
231-
const result = PackageInstallResponseSchema.parse({
224+
it('refuses the { package } wrapper no surface sends, at data.manifest and data.source', () => {
225+
const result = PackageInstallResponseSchema.safeParse({
232226
success: true,
233-
data: {
234-
package: {
235-
manifest: { id: 'com.acme.crm', name: 'acme_crm', version: '1.0.0', type: 'plugin' },
236-
source: 'authored',
237-
status: 'installed',
238-
enabled: true,
239-
},
240-
namespaceConflicts: [{
241-
type: 'namespace_conflict',
242-
requestedNamespace: 'acme',
243-
conflictingPackageId: 'com.other.plugin',
244-
conflictingPackageName: 'Other Plugin',
245-
suggestion: 'acme_crm',
246-
}],
247-
},
227+
data: { package: ROW, message: 'Package installed successfully' },
248228
});
249-
expect(result.data.namespaceConflicts).toHaveLength(1);
250-
expect(result.data.namespaceConflicts![0].suggestion).toBe('acme_crm');
229+
expect(result.success).toBe(false);
230+
const paths = result.error!.issues.map((i) => i.path.join('.'));
231+
expect(paths).toEqual(expect.arrayContaining(['data.manifest', 'data.source']));
232+
});
233+
234+
it('is the output the installPackage contract binds', () => {
235+
expect(PackageApiContracts.installPackage.output).toBe(PackageInstallResponseSchema);
251236
});
252237
});
253238

‎packages/spec/src/api/package-api.zod.ts‎

Lines changed: 27 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -522,22 +522,35 @@ export type PackageInstallBody = z.input<typeof PackageInstallBodySchema>;
522522
export type PackageInstallBodyParsed = z.infer<typeof PackageInstallBodySchema>;
523523

524524
/**
525-
* Response after installing a package.
525+
* Response after installing a package (`POST /api/v1/packages`): the envelope,
526+
* with the installed row itself as `data`.
527+
*
528+
* ## `data` is the BARE row the door serves
529+
*
530+
* The install door answers `success(pkg)` with status `201`, where `pkg` is the
531+
* `InstalledPackage` row `SchemaRegistry.installPackage` recorded, on both
532+
* install arms (the protocol service's and the no-protocol fallback). So `data`
533+
* is {@link InstalledPackageSchema}, reused rather than restated.
534+
*
535+
* Until #30464 this declared `data: { package, dependencyResolution?,
536+
* namespaceConflicts?, message? }`, a wrapper no surface ever sent: an
537+
* integrator coding against it read `data.package` and got `undefined`. The
538+
* first-party client had already followed the wire (#12034:
539+
* `client.packages.install` resolves to `InstalledPackage`). ⛔ The fix is the
540+
* contract following the wire, never the door growing the old envelope.
541+
*
542+
* The row is at the AUTHORING stage, because this door installs the manifest
543+
* its own request schema ({@link PackageInstallBodySchema}) declares. It carries
544+
* no `writable` / `disableable`: those are the READ doors' per-read verdicts
545+
* (`InstalledPackageAtEitherStageSchema`, `./package-api-assembled.zod.ts`),
546+
* which this door does not compute.
547+
*
548+
* Contract-vs-wire pin (the real dispatcher's answer parsed with
549+
* `PackageApiContracts.installPackage.output`):
550+
* `packages/client/src/packages-write-envelope.test.ts`.
526551
*/
527552
export const PackageInstallResponseSchema = lazySchema(() => BaseResponseSchema.extend({
528-
data: z.object({
529-
package: InstalledPackageSchema.describe('Installed package details'),
530-
dependencyResolution: DependencyResolutionResultSchema.optional()
531-
.describe('Dependency resolution result'),
532-
namespaceConflicts: z.array(z.object({
533-
type: z.literal('namespace_conflict').describe('Error type'),
534-
requestedNamespace: z.string().describe('Requested namespace'),
535-
conflictingPackageId: z.string().describe('Conflicting package ID'),
536-
conflictingPackageName: z.string().describe('Conflicting package name'),
537-
suggestion: z.string().optional().describe('Suggested alternative'),
538-
})).optional().describe('Namespace conflicts detected'),
539-
message: z.string().optional().describe('Installation status message'),
540-
}),
553+
data: InstalledPackageSchema.describe('The installed package row, served bare as `data`: the row the registry recorded, at the authoring stage'),
541554
}).describe('Install package response'));
542555
export type PackageInstallResponse = z.input<typeof PackageInstallResponseSchema>;
543556
/** Post-parse shape of {@link PackageInstallResponse} — defaults applied, transforms run (ADR-0122). */

0 commit comments

Comments
 (0)