pnpm run build fails with misleading MISSING_EXPORT when deleted packages leave manifest-less directories behind

[danbao]

Summary

After a refactor that deletes or moves packages, any working copy that has been built before accumulates manifest-less directories containing only ignored build output (lib/, node_modules/, *.tsbuildinfo). git clean -fd does not remove them (they are gitignored), and the tsdown workspace glob (packages/*/*, vendor/*, apps/cli) still matches them. The stale lib trees then get bundled, and the build fails with confusing MISSING_EXPORT errors that reference paths from before the refactor.

Environment

• master @ cd5ef814 (merge of 历史记录加载不出来的bug，可以这么改 #3248, dsh-0.1.2-alpha.1)
• macOS 15 arm64, node v24.19.0, pnpm 11.7.0
• Observed from a desktop client that runs git reset --hard + git clean -fd + pnpm install + pnpm run build on every update

What happened in the wild

After updating to cd5ef814, the build failed with Build failed with 7 errors repeated across ~134 tsdown projects (a 300 MB log), all pointing at exports that no longer exist:

[MISSING_EXPORT] "apiRemoteSubagentOwnershipError" is not exported by "../../api/remotes/src/index.ts".
[MISSING_EXPORT] "ApiRemoteSubagentSessionOwnership" is not exported by "../../api/remotes/src/index.ts".
ERROR  Error: Build failed with 7 errors:   ← ×134

Note ../../api/remotes/src/index.ts: the package had already moved to packages/api/remotes. The path comes from stale build output of a deleted package (packages/host/apiproxy), not from anything in the current tree.

Root cause

1. The refactor deleted packages (e.g. packages/host/apiproxy, packages/client/runtime, packages/examples/*). git reset --hard removes their tracked files, but the gitignored lib/ and node_modules/ survive git clean -fd, leaving manifest-less directories.
2. tsdown's workspace enumeration matches directories by glob and does not require package.json. For a directory without its own tsdown.config.ts, config loading walks up to the root config, whose host-face entry is lib/types/{index,invariant,startup}.js.
3. The stale lib/types/*.js resolves as the entry and rolldown bundles it; its imports reference symbols the refactor removed → MISSING_EXPORT. The misleading relative path is resolved from the stale artifact's own location.

Minimal reproduction (30 seconds, on a built tree)

mkdir -p packages/host/apiproxy/lib/types
cat > packages/host/apiproxy/lib/types/index.js <<'REPRO'
import { apiRemoteSubagentOwnershipError } from '@deepseek-ai/dsh-api-remotes';
export { apiRemoteSubagentOwnershipError };
REPRO
pnpm exec tsdown --env.DSH_BUILD_FACE host   # → MISSING_EXPORT, exits 1
rm -rf packages/host/apiproxy                 # → build works again

scripts/clean.ts already handles exactly this case (manifest-less directories whose content is only known residue are removed; unknown content aborts the clean), and pnpm run clean unblocked us — a full pnpm install && pnpm run build afterwards succeeds (393 tsdown builds, 218 client artifacts recorded). But nothing runs or even points to the clean script when the build fails, so the failure looks like a broken tree at the new commit.

Suggestions

1. Run the orphan/residue planning from scripts/clean.ts (plan-only) at the start of scripts/build.ts and fail with an actionable message, e.g. "stale manifest-less package directories found — run pnpm run clean".
2. If feasible in the tsdown workspace config, skip directories without package.json during workspace enumeration.
3. Document pnpm run clean as the recovery step after refactors that delete or move packages.

[PerryLink]

Short answer: your diagnosis matches the source exactly, master still has this shape, and pnpm run clean remains the right recovery step.

What I confirmed against master (0.1.6-alpha.1):

• The root tsdown config still sweeps by glob and still disables cleaning, tsdown.config.ts:19-29:

workspace: client ? ['vendor/*', 'packages/*/*', 'apps/cli'] : [...]
entry: client ? '' : ['lib/types/{index,invariant,startup}.js'],
...
clean: false,

• The build script runs nothing that plans or points at the clean step. package.json:20 is "build": "tsx scripts/build.ts", and scripts/build.ts:43-46 just removes the client-build record then runs build:native-system, build:lib, build:web. So on failure nothing tells you to run clean — exactly as you observed.
• scripts/clean.ts really does handle manifest-less directories: line 7 defines knownOrphanEntries = new Set(['node_modules', 'lib', '.typecheck']), lines 91-108 remove a package dir only when every remaining entry is known residue, and lines 102-116 make unknown content abort the whole clean:

const unknown = entries.filter(entry => !knownOrphanEntries.has(entry) && !entry.endsWith('.tsbuildinfo'))
if (unknown.length > 0) { unsafeOrphans.push(...) } else { await this.addIfPresent(targets, packageDirectory, canonicalRoot) }

• .gitignore:4 lists lib/, so git clean -fd (without -x) genuinely leaves those dirs behind.
• The tsdown mechanism is also as you described. Installed tsdown is 0.22.2; for an explicit glob list its workspace expansion matches directories only, with no package.json check — node_modules/tsdown/dist/build-BxT2lm9L.mjs:65-71:

else packages = (await glob(packages, { ignore: exclude, cwd: rootCwd, onlyDirectories: true, absolute: true, expandDirectories: false }))...

and line 82 mergeConfig(normalized, config) folds the root config — including that lib/types/... entry — into every matched directory. A manifest-less dir holding a stale lib/types/*.js then bundles and MISSING_EXPORTs, with paths resolved from the stale artifact's own location.

Is master still affected? The shape is unchanged (globs, entry, clean:false all identical), but I scanned packages/*/*, vendor/*, and apps/* on master and found zero manifest-less directories, so a fresh clone builds without this problem. It only bites a working copy that was built before a refactor, then updated — as you said. Your repro path packages/host/apiproxy no longer exists on master (the refactor landed); the mechanism itself will reappear at the next package deletion.

What to do: pnpm run clean (safe — aborts on unknown content), or delete the manifest-less dirs by hand, or git clean -xdf. Risk note on -xdf: it removes every untracked and ignored file in the tree, including node_modules, .dsh-build, and anything local you keep there; a fresh clone is the blunt alternative.

Your suggestions 1 (plan-only orphan check at the start of scripts/build.ts with an actionable message) and 3 (document clean as recovery) both look sensible to me; suggestion 2 needs a change in tsdown's workspace enumeration, which the current 0.22.2 doesn't offer.

Not verified: I didn't run a full build on master myself, and your 393-build/218-artifact numbers are your environment's. If it happens again, the first MISSING_EXPORT line plus the swept directory list would confirm which dir got bundled.