feat(release): publish package source, declaration maps, and documentation

Every release member publishes its TypeScript source and the declaration
maps that resolve into it, and @deepseek-ai/dsh publishes the repository
Markdown documentation staged from docs/ at prepack time.

The ./src/* export most members already declared now resolves for an
installed consumer, and a consumer editor follows a declaration to the
implementation. Bundled JavaScript maps stay unpublished; the vendored
family and the Desktop runtime file policy are unchanged.

Rationale: .agents/notes/implemented/process/2026-10-08-published-source-and-docs.md
This commit is contained in:
turtle1999 committed 2026-10-08 15:30:35 +08:00
1 parent 67c2fc749b
commit caa7111f28
356 files changed
+1331 -415

No files matched your search

+10 -6
View File
@@ -293,16 +293,16 @@ describe('package payload constraints', () => {
[{ import: './art/icon.svg', default: './art/fallback.svg' }, ['art/icon.svg', 'art/fallback.svg']],
[['./art/icon.svg', './art/icon.svg'], ['art/icon.svg']],
] as const)('includes exported icon targets in the canonical payload: %j', (icon, expected) => {
expect(expectedDshPackageFiles({ exports: { './icon': icon } })).toEqual([...expected, 'lib/index.js', 'lib/types/**/*.d.ts'])
expect(expectedDshPackageFiles({ exports: { './icon': icon } })).toEqual([...expected, 'lib/index.js', 'lib/types/**/*.d.ts', 'lib/types/**/*.d.ts.map', 'src'])
})
it.each(['icon.svg', './icon.svg'])('includes and deduplicates manifest icon %s', (icon) => {
expect(expectedDshPackageFiles({ icon, exports: { './icon': './icon.svg' } })).toEqual(['icon.svg', 'lib/index.js', 'lib/types/**/*.d.ts'])
expect(expectedDshPackageFiles({ icon, exports: { './icon': './icon.svg' } })).toEqual(['icon.svg', 'lib/index.js', 'lib/types/**/*.d.ts', 'lib/types/**/*.d.ts.map', 'src'])
})
it('includes manifest, root, and subpath icon targets', () => {
expect(expectedDshPackageFiles({ icon: './legacy.svg', exports: { './icon': './fallback.svg', './search/icon': './search.svg' } })).toEqual([
'legacy.svg', 'fallback.svg', 'search.svg', 'lib/index.js', 'lib/types/**/*.d.ts',
'legacy.svg', 'fallback.svg', 'search.svg', 'lib/index.js', 'lib/types/**/*.d.ts', 'lib/types/**/*.d.ts.map', 'src',
])
})
@@ -323,7 +323,7 @@ describe('package payload constraints', () => {
{ exports: { './search/locale/*.json': './z/*.json', './locale/*.json': './a/*.json' }, resources: ['a/*.json', 'z/*.json'] },
])('includes declared locale resources in the canonical payload: $exports', ({ exports, resources }) => {
expect(expectedDshPackageFiles({ name: '@deepseek-ai/dsh-localized', exports })).toEqual([
...resources, 'lib/index.js', 'lib/types/**/*.d.ts',
...resources, 'lib/index.js', 'lib/types/**/*.d.ts', 'lib/types/**/*.d.ts.map', 'src',
])
})
@@ -336,7 +336,7 @@ describe('package payload constraints', () => {
'./locale/zh.json': null,
'./locale/fr.json': { types: './locale/fr.d.ts' },
},
})).toEqual(['lib/index.js', 'lib/types/**/*.d.ts'])
})).toEqual(['lib/index.js', 'lib/types/**/*.d.ts', 'lib/types/**/*.d.ts.map', 'src'])
})
it.each(['agent-team', 'agent-team-profile', 'auto-review', 'client-ui-agent-team', 'tool-agent-team'])(
@@ -367,6 +367,8 @@ describe('package payload constraints', () => {
'lib/index.js',
'cordis.patch.yml',
'lib/types/**/*.d.ts',
'lib/types/**/*.d.ts.map',
'src',
])
expect(expectedDshPackageFiles({
name: '@deepseek-ai/dsh-private-profile',
@@ -376,6 +378,8 @@ describe('package payload constraints', () => {
'cordis.patch.yml',
'layers/web.patch.yml',
'lib/types/**/*.d.ts',
'lib/types/**/*.d.ts.map',
'src',
])
})
@@ -392,7 +396,7 @@ it('publishes CLI runtime declarations and rejects a payload that omits them', (
const manifest = JSON.parse(readFileSync(new URL('../apps/cli/package.json', import.meta.url), 'utf8')) as WorkspaceManifest['manifest']
expect(checkWorkspaceManifest({ dir: 'apps/cli', manifest })).toEqual([])
expect(checkWorkspaceManifest({ dir: 'apps/cli', manifest: { ...manifest, files: ['lib/*.js'] } }))
.toEqual([expect.stringContaining('@deepseek-ai/dsh: package.json files must be ["lib/*.js","lib/types/*.d.ts"]')])
.toEqual([expect.stringContaining('@deepseek-ai/dsh: package.json files must be ["lib/*.js","lib/types/*.d.ts","lib/types/*.d.ts.map","docs","src"]')])
})
it('requires the shared Web injection entry in the published payload', () => {
+15 -11
View File
@@ -49,10 +49,6 @@ const publicNativePackages = new Set([
'@deepseek-ai/node-addon-system-linux-arm64',
'@deepseek-ai/node-addon-system-linux-x64',
])
/** Deliberate source payloads whose exact bytes are part of the package's audit surface. */
const publicationSourceAllowlist: Readonly<Record<string, readonly string[]>> = {
'@deepseek-ai/node-addon-system': ['src/main.c', 'src/flock.c'],
}
/** Public source home recorded in maintained package manifests. */
const publishedRepositoryUrl = 'git+https://github.com/deepseek-ai/deepseek-harness.git'
/** Packages that participate in the experimental policy. */
@@ -63,14 +59,16 @@ const standardReleaseMemberDirectory = /^(?:packages\/(?!experimental\/)[^/]+\/[
const desktopApplicationDirectory = 'apps/desktop'
const localArtifactDirs = new Set(['node_modules'])
const appPackageFiles: Readonly<Record<string, readonly string[]>> = {
'@deepseek-ai/dsh': ['lib/*.js', 'lib/types/*.d.ts'],
// `docs` carries the repository's Markdown documentation, staged by
// `scripts/stage-dsh-docs.ts` before packing.
'@deepseek-ai/dsh': ['lib/*.js', 'lib/types/*.d.ts', 'lib/types/*.d.ts.map', 'docs', 'src'],
'@deepseek-ai/dsh-desktop-host': [
'lib/index.js', 'lib/cli.js',
],
// Sourcemaps stay out by payload policy; the worker-preview surface
// (dist/preview.html and dist/preview/) backs opt-in experimental
// Bundled JavaScript maps stay out by payload policy; the worker-preview
// surface (dist/preview.html and dist/preview/) backs opt-in experimental
// packages and is not published.
'@deepseek-ai/dsh-web-frontend': ['dist', '!dist/**/*.map', '!dist/preview.html', '!dist/preview'],
'@deepseek-ai/dsh-web-frontend': ['dist', '!dist/**/*.map', '!dist/preview.html', '!dist/preview', 'src'],
}
/** The subset of package.json fields this constraint check cares about. */
@@ -291,6 +289,10 @@ export function expectedDshPackageFiles(manifest: PackageManifest): readonly str
// declarations.
...usesEmittedTreeDefaults(manifest) ? ['lib/types/**/*.js'] : [],
'lib/types/**/*.d.ts',
// A published declaration map plus `src` lets a consumer editor open the
// implementation behind an exported declaration, and lets a plugin author
// read it without a repository checkout.
'lib/types/**/*.d.ts.map',
...hasExportPair(manifest, './typert', './lib/typert.host.d.ts', './lib/typert.host.js')
? ['lib/typert.host.js', 'lib/typert.host.d.ts']
: [],
@@ -298,8 +300,11 @@ export function expectedDshPackageFiles(manifest: PackageManifest): readonly str
? ['lib/typert.client.js', 'lib/typert.client.d.ts']
: [],
...hasTypertRemoteNavigation(manifest)
? ['lib/typert.remote-client.js', 'lib/typert.remote-client.d.ts']
// The generated Remote declaration carries a `sourceMappingURL` its map
// resolves, and that map resolves the Host method through `src`.
? ['lib/typert.remote-client.js', 'lib/typert.remote-client.d.ts', 'lib/typert.remote-client.d.ts.map']
: [],
'src',
]
}
@@ -461,9 +466,8 @@ export function checkWorkspaceManifest({ dir, manifest }: WorkspaceManifest): st
}
if (manifest.name?.startsWith('@deepseek-ai/')) {
const allowedSources = publicationSourceAllowlist[manifest.name] ?? []
for (const file of manifest.files ?? []) {
if (isForbiddenPublicationFile(file) && !allowedSources.includes(file)) {
if (isForbiddenPublicationFile(file)) {
errors.push(`${label}: package.json files must not publish ${JSON.stringify(file)}`)
}
}
+21 -25
View File
@@ -15,47 +15,43 @@ describe('publication payload policy', () => {
it.each([
'lib/index.js',
'lib/types/index.d.ts',
'lib/types/index.d.ts.map',
'lib/typert.remote-client.d.ts.map',
'lib/styles/base.css',
])('accepts %s', (file) => {
expect(isForbiddenPublicationFile(file)).toBe(false)
})
it.each([
'src',
'./src',
'src/',
'src/index.ts',
'./src/index.ts',
String.raw`src\index.ts`,
'lib/types/index.d.ts.map',
'./lib/types/index.d.ts.map',
'lib/typert.remote-client.d.ts.map',
])('accepts %s', (file) => {
expect(isForbiddenPublicationFile(file)).toBe(false)
})
it.each([
'lib/client.js.map',
'./lib/client.js.map',
'lib/types/index.js.map',
String.raw`lib\client.js.map`,
])('rejects static manifest path %s', (file) => {
expect(isForbiddenPublicationFile(file)).toBe(true)
})
it('rejects source members in packed tarballs', () => {
expect(validateFixtureTarball([
'package/package.json',
'package/src/index.ts',
])).toThrow('fixture.tgz publishes source file package/src/index.ts')
})
it('rejects source maps in packed tarballs', () => {
expect(validateFixtureTarball([
'package/package.json',
'package/lib/types/index.d.ts.map',
])).toThrow('fixture.tgz publishes source map package/lib/types/index.d.ts.map')
expect(validateFixtureTarball([
'package/package.json',
'package/lib/typert.remote-client.d.ts.map',
])).toThrow('fixture.tgz publishes source map package/lib/typert.remote-client.d.ts.map')
it('rejects bundled JavaScript maps in packed tarballs', () => {
expect(validateFixtureTarball([
'package/package.json',
'package/lib/client.js.map',
])).toThrow('fixture.tgz publishes source map package/lib/client.js.map')
])).toThrow('fixture.tgz publishes JavaScript map package/lib/client.js.map')
})
it('accepts source, declaration maps, and declarations in packed tarballs', () => {
expect(validateFixtureTarball([
'package/package.json',
'package/src/index.ts',
'package/lib/types/index.d.ts',
'package/lib/types/index.d.ts.map',
'package/lib/typert.remote-client.d.ts.map',
])).not.toThrow()
})
it('accepts a clean packed tarball', () => {
+7 -16
View File
@@ -23,33 +23,24 @@ function payloadPath(file: string): string {
}
/**
* Whether a package payload path exposes source or map intermediates. Maps
* serve editor navigation during development, where a workspace consumer
* resolves their source through the package link; a published map resolves
* nothing, so no payload publishes one.
* Whether a package payload path exposes JavaScript map intermediates. A
* declaration map pairs with the source and the declaration a consumer
* reaches; a JavaScript map describes bundler output that no published entry
* pairs with, so no payload publishes one.
* @param file - manifest path or tarball member to classify.
* @returns whether publishing this path is forbidden.
*/
export function isForbiddenPublicationFile(file: string): boolean {
const normalized = payloadPath(file)
return normalized === 'src'
|| normalized.startsWith('src/')
|| normalized.endsWith('.d.ts.map')
|| normalized.endsWith('.js.map')
return payloadPath(file).endsWith('.js.map')
}
/**
* Reject source and map members in a packed npm tarball.
* Reject bundled JavaScript map members in a packed npm tarball.
* @param files - tarball members to validate.
* @param context - tarball identity named in the failure.
*/
export function validateTarballPayload(files: readonly string[], context: string): void {
for (const file of files) {
if (!isForbiddenPublicationFile(file)) continue
const normalized = payloadPath(file)
if (normalized === 'src' || normalized.startsWith('src/')) {
throw new Error(`${context} publishes source file ${file}`)
}
throw new Error(`${context} publishes source map ${file}`)
if (isForbiddenPublicationFile(file)) throw new Error(`${context} publishes JavaScript map ${file}`)
}
}
+15 -2
View File
@@ -387,12 +387,25 @@ describe('release families', () => {
const harness = member('packages/a/library', '@deepseek-ai/dsh-library')
const vendored = member('vendor/cordis', '@deepseek-ai/cordis')
expect(() => { dsh.validatePayload(harness, ['package/lib/index.js', 'package/src/index.ts']) })
.toThrow(/publishes source file/)
expect(() => { dsh.validatePayload(harness, ['package/lib/index.js', 'package/lib/client.js.map']) })
.toThrow(/publishes JavaScript map/)
expect(() => { dsh.validatePayload(harness, ['package/lib/index.js', 'package/src/index.ts']) }).not.toThrow()
expect(() => { vendor.validatePayload(vendored, ['package/lib/index.js', 'package/src/index.ts']) }).not.toThrow()
expect(() => { vendor.validatePayload(vendored, []) }).toThrow(/empty tarball/)
})
it('requires the installed package payload the staging hook supplies', () => {
const dsh = releaseFamily('dsh')
const installed = member('apps/cli', '@deepseek-ai/dsh')
expect(() => { dsh.validatePayload(installed, ['package/lib/index.js', 'package/src/bin.ts']) })
.toThrow(/@deepseek-ai\/dsh packed no documentation/)
expect(() => { dsh.validatePayload(installed, ['package/lib/index.js', 'package/docs/guide.md']) })
.toThrow(/@deepseek-ai\/dsh packed no source/)
expect(() => { dsh.validatePayload(installed, ['package/lib/index.js', 'package/docs/guide.md', 'package/src/bin.ts']) })
.not.toThrow()
})
it('drives the installed entry only for the family that publishes one', () => {
expect(releaseFamily('dsh').installedEntry).toEqual({ packageName: '@deepseek-ai/dsh', binPath: 'lib/bin.js' })
expect(releaseFamily('vendor').installedEntry).toBeUndefined()
+15 -6
View File
@@ -387,12 +387,22 @@ class DshFamily extends ReleaseFamily {
}
/**
* Reject source and declaration-map members, the repository's publication policy.
* Reject bundled JavaScript maps, and require the installed package to carry
* the documentation and source its manifest promises. `docs` exists only
* because `prepack` stages it, so a pack run that skips lifecycle scripts
* would otherwise publish the package without it.
* @param member - the packed member.
* @param files - every path inside its tarball.
*/
validatePayload(member: ReleaseMember, files: readonly string[]): void {
validateTarballPayload(files, member.name)
if (member.name !== this.installedEntry.packageName) return
if (!files.some(file => file.startsWith('package/docs/') && file.endsWith('.md'))) {
throw new Error(`${member.name} packed no documentation`)
}
if (!files.some(file => file.startsWith('package/src/') && file.endsWith('.ts'))) {
throw new Error(`${member.name} packed no source`)
}
}
/** Publish every advertised on-demand package before the installation that offers it. */
@@ -449,11 +459,10 @@ class VendorFamily extends ReleaseFamily {
* Require the payload the vendored manifest declares, including upstream's
* `src` tree and declaration maps.
*
* The harness policy that rejects both does not apply here: these manifests
* export `./src/*` for source navigation, so dropping `src` would publish a
* package whose export map points at absent files. What must hold instead is
* that every path the manifest selects is present, which `files` already
* decides and `pnpm pack` already enforces.
* Upstream's manifest owns that payload, so this family enforces no shape of
* its own beyond a nonempty tarball. What must hold is that every path the
* manifest selects is present, which `files` already decides and `pnpm pack`
* already enforces.
* @param member - the packed member.
* @param files - every path inside its tarball.
*/
+3 -3
View File
@@ -307,15 +307,15 @@ describe('release pack CLI', () => {
it('validates every parallel tarball before recording the publish order', async () => {
const root = fixture()
packageFixture(root, 'packages/util/alpha', '@deepseek-ai/alpha')
packageFixture(root, 'packages/util/zebra', '@deepseek-ai/zebra', { files: ['lib/index.js', 'src/index.ts'] })
write(join(root, 'packages/util/zebra/src/index.ts'), 'export const source = 1\n')
packageFixture(root, 'packages/util/zebra', '@deepseek-ai/zebra', { files: ['lib/index.js', 'lib/client.js.map'] })
write(join(root, 'packages/util/zebra/lib/client.js.map'), '{"version":3}\n')
write(join(root, 'apps/web/dist/index.html'), '<main></main>')
writeClientBuildRecord(root, officialClientBuildEnvironment(root, { DSH_CLIENT_COMMIT_HASH: commit }))
const result = await runPack(root, ['--family', 'dsh', '--concurrency', '8'])
expect(result.status).not.toBe(0)
expect(result.stderr).toContain('@deepseek-ai/zebra publishes source file package/src/index.ts')
expect(result.stderr).toContain('@deepseek-ai/zebra publishes JavaScript map package/lib/client.js.map')
expect(readdirSync(join(root, 'packed')).filter(name => name.endsWith('.tgz'))).toHaveLength(2)
expect(existsSync(join(root, 'packed', PUBLISH_ORDER_FILE))).toBe(false)
})
+58
View File
@@ -0,0 +1,58 @@
import { existsSync, mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, describe, expect, it } from 'vitest'
import { stageDshDocs } from './stage-dsh-docs.ts'
const roots: string[] = []
function temporaryRoot(): string {
const root = mkdtempSync(join(tmpdir(), 'dsh-stage-docs-'))
roots.push(root)
return root
}
function write(root: string, path: string, contents = '# fixture\n'): void {
const target = join(root, path)
mkdirSync(join(target, '..'), { recursive: true })
writeFileSync(target, contents)
}
afterEach(() => {
for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
})
describe('documentation staging', () => {
it('copies reader-facing documents and assets without the tooling-owned records', async () => {
const source = join(temporaryRoot(), 'docs')
const destination = join(temporaryRoot(), 'cli', 'docs')
write(source, 'guide/index.md')
write(source, 'guide/index.zh.md')
write(source, 'guide/index.i18n.yaml')
write(source, 'images/diagram.png', 'png')
write(source, 'persistence-changes/v1/changes.md')
write(source, 'persistence-changes/README.md')
write(source, 'AGENTS.md')
await stageDshDocs(source, destination)
expect(existsSync(join(destination, 'guide', 'index.md'))).toBe(true)
expect(existsSync(join(destination, 'guide', 'index.zh.md'))).toBe(true)
expect(existsSync(join(destination, 'images', 'diagram.png'))).toBe(true)
expect(existsSync(join(destination, 'AGENTS.md'))).toBe(true)
expect(existsSync(join(destination, 'guide', 'index.i18n.yaml'))).toBe(false)
expect(existsSync(join(destination, 'persistence-changes'))).toBe(false)
})
it('replaces a previous copy instead of merging into it', async () => {
const source = join(temporaryRoot(), 'docs')
const destination = join(temporaryRoot(), 'cli', 'docs')
write(source, 'kept.md')
write(destination, 'removed.md')
await stageDshDocs(source, destination)
expect(existsSync(join(destination, 'kept.md'))).toBe(true)
expect(existsSync(join(destination, 'removed.md'))).toBe(false)
})
})
+49
View File
@@ -0,0 +1,49 @@
/** Stage the reader-facing documentation inside the published `dsh` package. */
import { cp, rm } from 'node:fs/promises'
import { join, relative, sep } from 'node:path'
import { fileURLToPath } from 'node:url'
/** Repository root, resolved from this script rather than the invoking directory. */
const REPOSITORY_ROOT = fileURLToPath(new URL('..', import.meta.url))
/** Generated per-release migration records; an installed package carries the current contract instead. */
const EXCLUDED_DIRECTORY = 'persistence-changes'
/** Translation alignment records the documentation gates own; a reader never opens one. */
const EXCLUDED_SUFFIX = '.i18n.yaml'
/**
* Replace a package's `docs` directory with the documentation a reader needs.
*
* Runs from the `prepack` lifecycle of `@deepseek-ai/dsh`, so packing the
* package and packing the release set both publish the same Markdown.
* @param source - Documentation root to copy; defaults to the repository `docs`.
* @param destination - Package directory to replace; defaults to `apps/cli/docs`.
* @returns Resolves after the destination holds the filtered copy.
*/
export async function stageDshDocs(
source: string = join(REPOSITORY_ROOT, 'docs'),
destination: string = join(REPOSITORY_ROOT, 'apps', 'cli', 'docs'),
): Promise<void> {
await rm(destination, { recursive: true, force: true })
await cp(source, destination, {
recursive: true,
filter: entry => !isExcluded(source, entry),
})
}
/**
* Whether one source path is tooling-owned or generated rather than reader-facing.
* @param source - Documentation root the entry belongs to.
* @param entry - Absolute source path offered to the copy filter.
* @returns whether the copy skips this entry.
*/
function isExcluded(source: string, entry: string): boolean {
const path = relative(source, entry).split(sep).join('/')
return path === EXCLUDED_DIRECTORY
|| path.startsWith(`${EXCLUDED_DIRECTORY}/`)
|| path.endsWith(EXCLUDED_SUFFIX)
}
if (import.meta.main) await stageDshDocs()
+2
View File
@@ -142,6 +142,7 @@ export const TRANSLATION_SCOPE_GLOB_EXCLUDES = [
'**/__pycache__/**',
'**/.pytest_cache/**',
'apps/web/dist/**',
'apps/cli/docs/**',
'.artifacts/**',
'python/sdk-runtime/src/deepseek_harness_runtime/runtime/**',
'vendor/**',
@@ -154,6 +155,7 @@ function isTranslationSourceExcluded(file: string): boolean {
|| segment.startsWith('.doc-typecheck-')
|| segment.startsWith('.node-next-types-'))
|| file.startsWith('apps/web/dist/')
|| file.startsWith('apps/cli/docs/')
|| file.startsWith('python/sdk-runtime/src/deepseek_harness_runtime/runtime/')
}