WorkspaceTypertGenerator silently emits no artifacts for an out-of-workspace package

[ethanj]

Versions: dsh 0.1.1-rc.2, commit b150a551b8d465e31e418e1b2eaf5e79bbb7d28e, Node v24.16.0, pnpm 11.7.0, macOS.

What we were doing

Building an out-of-tree dsh bundle whose browser half calls its own host service. The documented path is a TypertRemoteService with @Remote methods, generating typert.host.js and typert.remote-client.js, which the client mounts via ctx.remote.$mount().

What happens

WorkspaceTypertGenerator discovers contributing packages through loadRegistrations, which requires both:

1. a TypeScript project reference reaching the package from the workspace's tsconfig.host.json;
2. the package root to sit under <workspace>/packages/ (isWithin(..., join(root, 'packages'))).

A package outside the workspace satisfies neither, and the generator does not report this: discover() returns an empty list and generate() emits zero artifacts with no error. A build can appear to have generated successfully and ship nothing.

The fallback — SRC weak parsing — is not usable here, because a browser client refuses SRC descriptors without strict codecs.

Reproduction

1. create a package outside the dsh checkout exporting a TypertRemoteService with @Remote methods and the ./typert / ./remote export faces;
2. run WorkspaceTypertGenerator(<packageDir>).discover(['host']);
3. observe an empty array, no diagnostic.

The workaround we use

Stage the package into a clean checkout at the pinned commit (packages/<org>/<pkg>), add a project reference to tsconfig.host.json, generate with the real API, copy the artifacts out, restore the tree, and vendor the results with input/output hashes so CI fails on drift. This produces correct strict descriptors — the resulting bundle mounts and renders in a real browser session — but it is ~60 lines of staging every third-party author has to rediscover.

What would help, in rough order of value

1. A diagnostic. discover() returning empty is the whole problem — an error naming the missing project reference or the packages/ constraint would have saved most of the time this cost.
2. A supported single-package entry point, e.g. generateForPackage(packageDir), that does not require the caller to be a workspace.
3. Documentation of the constraint, so an author knows up front that a third-party package must stage inside a checkout.

[nokkies]

The two gates you identified are real and the code reads exactly as you describe. But there is a third one ahead of both, and I think it is the one your reproduction actually hits.

WorkspaceTypertGenerator takes the workspace root, not a package directory

constructor(private readonly root: string) is documented as "directory containing face aggregate tsconfigs". loadRegistrations starts by resolving <root>/tsconfig.host.json and <root>/tsconfig.client.json, and skips a face outright when its aggregate is absent:

const aggregatePath = resolve(this.options.root, face === 'host' ? this.options.hostConfig : this.options.clientConfig)
if (!existsSync(aggregatePath)) continue

So WorkspaceTypertGenerator(<packageDir>).discover(['host']) finds no aggregate under <packageDir>, skips both faces, and returns [] before the project-reference and <root>/packages gates are ever consulted. Your staging workaround works partly because it fixes this too: it puts the package inside a real workspace and generates against that workspace's root.

That does not make the report invalid — an API that answers a wrong root with an empty array rather than an error is the defect you are describing. It does change where a fix can go.

The silence at the analyzer level is deliberate, and tested

Worth flagging before anyone patches loadRegistrations: I tried exactly that — throw when both face aggregates are absent — and it breaks an existing contract on purpose, not by accident. type-model.spec.ts has a case named "handles empty selections" whose first assertion is a freshly created empty directory:

expect(new WorkspaceAnalyzer({ root: empty }).analyze()).toEqual({ faces: [], crossFaceLinks: [] })

and WorkspaceAnalyzerOptions.hostConfig documents "absent files are skipped". A workspace shipping a host face and no client face depends on that, so "no aggregate" cannot be promoted to an error at this level without a design decision about the single-face case.

Where the diagnostic can go instead

generate() already validates one direction: every emitted artifact must be exported from its package manifest at the right subpath — that is validateExport, and it throws with a precise message.

The unchecked direction is the converse, and it is exactly your failure: a package whose manifest declares ./typert (or ./client/typert) and files entries for it, but which produced no artifact. That is a manifest stating an intent the build did not satisfy, it needs no guess about what the caller wanted, and it does not disturb the empty-workspace contract, because a workspace with no such declarations still legitimately emits nothing.

Two smaller things in the same spirit:

• discover() returning [] is the one call that could cheaply say why — reporting which aggregates it looked for and did not find would have made your case self-diagnosing without changing any behaviour.
• The class doc says "directory containing face aggregate tsconfigs", but the constructor parameter is just root, which reads as "wherever my project is". workspaceRoot would have cost nothing and is the part I would fix first.

[ethanj]

You are right about the third gate, and it splits my report into two cases I had collapsed into one.

The minimal reproduction as I wrote it — a bare package directory with only the export faces — hits your missing-aggregate skip first and never reaches the two gates I named. But our real first encounter was one gate later: we had already learned the generator wants a tsconfig.host.json marker, so our package carried one at its root — with include globs and no references. That got past the aggregate check, and loadRegistrations then walked zero project references to zero packages and returned the same empty answer. So there are (at least) three stacked ways to arrive at silent-empty, and which one you hit depends on how much of the workspace shape you have already cargo-culted. That layering is itself part of the cost: each gate you satisfy moves you to the next silent failure with no signal that you are making progress.

On the empty-selections contract: agreed, and thank you for testing the naive fix before anyone ships it. A single-face workspace is legitimate and an analyzer-level throw would break it; I withdraw the implied "throw on empty" framing from my report.

Your converse-of-validateExport placement is exactly right, and I can confirm it against our failure precisely: our staged manifest declared ./typert and ./remote with files entries for all four artifacts, and generate() returned zero of them without complaint. A check that says "this manifest declares typert export faces and this run produced no artifact for them" would have converted our multi-hour diagnosis into a one-line error, needs no guess about intent, and — as you say — leaves a workspace with no such declarations free to emit nothing.

Ranking your three suggestions from our seat as the consumer who hit this: the converse check first (it catches all three silent paths whenever the manifest states intent), the discover() breadcrumb second (it catches the case where the manifest is also wrong), the root → workspaceRoot rename third (it prevents the initial misuse).

Offer: we maintain a deterministic out-of-tree regeneration harness for our package (staged generation against a pinned checkout, input/output hashes, CI drift gate). If a diagnostic patch materializes, I am happy to run it against all three silent shapes — no aggregate, aggregate without references, references without packages/ — and report which ones it converts to errors.

[weijiafu14]

@nokkies found the third gate and you split the report correctly. I want to add a data point on your ask #2 (a supported single-package entry point), because I am another out-of-tree author who hit this wall and took the other exit — and the price of that exit is worth knowing when this gets prioritised.

We gave up on the generated contract entirely. Same situation: an out-of-tree bundle whose browser half needs to talk to its own host service. Rather than the ~60 lines of staging you describe, we register our own route on ctx.webServer and the client half talks to that. Our own source records the reasoning:

Where the data comes from: this package's own route (/…/browser-state), not DSH's typed Remote system — that is a first-party generated contract, and an out-of-tree plugin talking to its own UI should carry its own channel.

So: two out-of-tree authors, two different escapes, one cause. That is the argument for #2 in a nutshell — today the supported-looking path is not reachable from outside the workspace, so everyone either reconstructs the workspace or leaves.

The cost of our exit, concretely, since it is the thing your staging hack buys you: no push channel. Our client half polls its own route — setInterval(pull, 4000) in one panel, 2000 in another — because rolling our own channel means rolling our own everything. Your staged-generation approach produces real strict descriptors and a real $mount(); ours produces a timer. Neither is what an out-of-tree author should have to choose between.

On your ask #1 (a diagnostic), which I would also put first: what makes this one bad is that it fails at build time and looks like success. A build that "generated" and shipped zero artifacts is worse than a build that failed, because the failure surfaces later, somewhere else, to someone else.

And it is not the only silent gate on this path. The runtime half has its own: the host's client-modules scan resolves a package's manifest by subpath, so a package that declares dsh.client but forgets to export ./package.json throws ERR_PACKAGE_PATH_NOT_EXPORTED — and that throw is swallowed and cached as "this is not a client package". Nothing renders, nothing appears in the console, and re-deploying does not clear it. That cost me a debugging session the same way discover() returning [] cost you one.

So an out-of-tree browser half currently has at least two independent places where the honest answer is an empty result and the observable answer is silence — build-time typert discovery and runtime client-module discovery. If someone is fixing the diagnostic in one, the other is the same shape and probably the same afternoon.

Interest disclosure: I maintain a third-party DSH plugin with a browser half, which is where both experiences come from. We do not modify the generator or the client loader and could not fix either; this is a second author's report, not a solution.

[denial123789]

I traced this against rc.2 (b150a55). There are three independent empty-selection gates here:

1. the constructor root is the workspace root containing the face aggregate configs, not the package root;
2. registration walks only parsed projectReferences, so include without references still selects nothing;
3. the referenced package realpath must be below <workspace>/packages, which also means a symlink to an external root is skipped.

The empty result itself cannot become a generic analyzer error: the upstream tests intentionally accept missing aggregates and aggregates with no references. A safer diagnostic is the converse at the generator/build layer: when an explicitly selected package or its manifest declares Typert intent but generation emits zero artifacts, fail with breadcrumbs for aggregate existence, parsed refs, canonical roots, containment, manifest name, and discovered faces.

For current external plugins, a reproducible workaround is a disposable checkout pinned to the exact upstream commit: stage the package under packages/community/..., add one explicit aggregate reference, require discover() to return the expected package/face, require an exact artifact allowlist, verify exports/files, record input/output digests, and compare regeneration in CI. Avoid a symlink because realpath containment still rejects it.

I wrote the complete failure router, manifest contracts, provenance shape, and a possible generateForPackage(packageDir) contract here: https://github.com/sandbaseai/deepseek-harness-handbook/blob/main/docs/en/plugin-development/out-of-tree-typert-generation.md

Disclosure: I maintain this independent SandBase handbook; it is not an official DeepSeek AI project.