Merge branch 'feat/plugin-mgmt-1-boot' into feat/plugin-mgmt-2-manager

# Conflicts:
#	apps/cli/src/bin.ts
#	docs/config-catalog.i18n.yaml
#	docs/config-catalog.md
#	docs/config-catalog.zh.md
#	packages/api/remotes/src/client/index.ts
#	packages/boot/app-boot/src/index.ts
#	packages/boot/app-boot/src/profile.ts
#	packages/host/README.i18n.yaml
#	packages/host/README.md
#	packages/host/README.zh.md
#	scripts/verify-package-readme-model-experience.ts
This commit is contained in:
Yichen Jiang committed 2026-09-08 16:52:09 +08:00
commit bb408abe28
2137 files changed
+73685 -9705

No files matched your search

+24 -4
View File
@@ -21,6 +21,8 @@ import { Command, CommanderError } from 'commander'
interface ProfileInvocation {
mode: 'profile'
profile: string
/** Shipped template used once to initialize a missing profile. */
fromDefaultProfile?: string | undefined
/** Extra patch-list overlays applied after the profile's own layer, in argv order. */
patches: string[]
/** Everything after the launcher's own flags, verbatim, for injected app plugins. */
@@ -31,6 +33,8 @@ interface ProfileInvocation {
interface DumpConfigInvocation {
mode: 'dump-config'
profile: string
/** Shipped template used once to initialize a missing profile. */
fromDefaultProfile?: string | undefined
/** Omit the profile's user layer and --patch overlays; print bundle layers only. */
defaultOnly: boolean
patches: string[]
@@ -52,6 +56,7 @@ interface BootOptions {
patch?: string[]
dumpConfig?: boolean
dumpDefaultConfig?: boolean
fromDefaultProfile?: string
}
/**
@@ -60,10 +65,18 @@ interface BootOptions {
*/
const collect = (value: string, previous: string[] = []): string[] => [...previous, value]
function rejectElectronProfile(program: Command, profile: string): void {
if (profile.toLowerCase() === 'desktop') {
program.error('error: profile "desktop" is managed exclusively by the Electron application')
}
}
/** The launcher's own help text; each app prints its own. */
const HELP_EXAMPLES = `
Examples:
dsh --profile web boot the web profile (same as: dsh web)
dsh --profile rescue --from-default-profile web
create rescue from the shipped web template, then boot it
dsh --profile headless "run the tests" answer one task, print the result, and exit
dsh --profile tui --patch ./extra.yml boot a custom profile with one extra overlay
dsh --profile tui --resume <session> arguments after the launcher flags reach the app
@@ -83,8 +96,9 @@ Examples:
function resolveBoot(program: Command, profile: string, options: BootOptions, args: string[]): DshInvocation {
const patches = options.patch ?? []
if (patches.includes('')) program.error('error: --patch needs a path')
if (options.fromDefaultProfile === '') program.error('error: --from-default-profile needs a name')
if (options.dumpConfig !== true && options.dumpDefaultConfig !== true) {
return { mode: 'profile', profile, patches, args }
return { mode: 'profile', profile, fromDefaultProfile: options.fromDefaultProfile, patches, args }
}
if (options.dumpConfig === true && options.dumpDefaultConfig === true) {
program.error('error: --dump-config and --dump-default-config are mutually exclusive')
@@ -99,7 +113,7 @@ function resolveBoot(program: Command, profile: string, options: BootOptions, ar
if (defaultOnly && patches.length > 0) {
program.error('error: --dump-default-config prints the bundle layers and takes no --patch')
}
return { mode: 'dump-config', profile, defaultOnly, patches }
return { mode: 'dump-config', profile, fromDefaultProfile: options.fromDefaultProfile, defaultOnly, patches }
}
/**
@@ -129,6 +143,7 @@ export function parseDshArgs(argv: readonly string[], version: string): DshInvoc
.enablePositionalOptions()
.argument('[args...]', 'arguments for the booted profile\'s app (see: dsh --profile <name> --help)')
.option('--profile <name>', 'the profile under $DSH_HOME/profiles to boot')
.option('--from-default-profile <name>', 'initialize a new custom profile from a shipped profile template')
.option('--patch <path>', 'extra patch-list overlay applied after the profile layer (repeatable)', collect)
.option('--dump-config', 'print the composed profile tree and exit')
.option('--dump-default-config', 'print the profile tree without its user layer or --patch overlays and exit')
@@ -141,6 +156,7 @@ export function parseDshArgs(argv: readonly string[], version: string): DshInvoc
}
const profile = options.profile
if (profile === '') program.error('error: --profile needs a name')
rejectElectronProfile(program, profile)
resolved = resolveBoot(program, profile, options, args)
})
@@ -148,8 +164,11 @@ export function parseDshArgs(argv: readonly string[], version: string): DshInvoc
const rejectParentOptions = (command: string): void => {
const parent = program.opts<BootOptions & { profile?: string }>()
if (parent.profile !== undefined || parent.patch !== undefined
|| parent.dumpConfig !== undefined || parent.dumpDefaultConfig !== undefined) {
program.error(`error: ${command} takes none of parent --profile, --patch, --dump-config, or --dump-default-config`)
|| parent.dumpConfig !== undefined || parent.dumpDefaultConfig !== undefined
|| parent.fromDefaultProfile !== undefined) {
program.error(
`error: ${command} takes none of parent --profile, --from-default-profile, --patch, --dump-config, or --dump-default-config`,
)
}
}
@@ -176,6 +195,7 @@ export function parseDshArgs(argv: readonly string[], version: string): DshInvoc
.action((args: string[], options: { profile: string }) => {
rejectParentOptions('plugin')
if (options.profile === '') program.error('error: --profile needs a name')
rejectElectronProfile(plugin, options.profile)
if (args.length === 0) program.error('error: plugin needs pnpm arguments to forward (e.g. add <package>)')
resolved = { mode: 'plugin', profile: options.profile, args }
})
+40 -24
View File
@@ -21,30 +21,46 @@ function readVersion(): string {
return typeof manifest.version === 'string' ? manifest.version : '0.0.0'
}
const invocation = parseDshArgs(process.argv.slice(2), readVersion())
/**
* Run the public dsh command-line interface.
* @returns a promise that settles when the selected command mode finishes.
*/
export async function runCli(): Promise<void> {
const invocation = parseDshArgs(process.argv.slice(2), readVersion())
switch (invocation.mode) {
case 'profile': {
const { runProfile } = await import('./profile-boot.ts')
await runProfile({
environment: loadLayeredEnv('dsh'),
profile: invocation.profile,
patchFiles: invocation.patches,
args: invocation.args,
})
break
switch (invocation.mode) {
case 'profile': {
const { runProfile } = await import('./profile-boot.ts')
await runProfile({
environment: loadLayeredEnv('dsh'),
profile: invocation.profile,
fromDefaultProfile: invocation.fromDefaultProfile,
patchFiles: invocation.patches,
args: invocation.args,
})
break
}
case 'plugin': {
const { runPlugin } = await import('./plugin.ts')
process.exit(await runPlugin(invocation.profile, invocation.args))
break
}
case 'dump-config': {
const { runDumpConfig } = await import('./dump-config.ts')
runDumpConfig(
invocation.profile,
invocation.defaultOnly,
invocation.patches,
invocation.fromDefaultProfile,
)
break
}
default:
invocation satisfies never
throw new Error(`dsh: unhandled invocation mode ${JSON.stringify(invocation)}`)
}
case 'plugin': {
const { runPlugin } = await import('./plugin.ts')
process.exit(await runPlugin(invocation.profile, invocation.args))
break
}
case 'dump-config': {
const { runDumpConfig } = await import('./dump-config.ts')
runDumpConfig(invocation.profile, invocation.defaultOnly, invocation.patches)
break
}
default:
invocation satisfies never
throw new Error(`dsh: unhandled invocation mode ${JSON.stringify(invocation)}`)
}
if (import.meta.main) {
await runCli()
}
+8 -2
View File
@@ -29,9 +29,15 @@ const NAME = 'dsh'
* (the recovery diagnostic for a broken `cordis.patch.yml`, which is then
* never parsed).
* @param patches - `--patch` overlay paths, in argv order.
* @param fromDefaultProfile - shipped template used once to initialize a missing profile.
*/
export function runDumpConfig(profile: string, defaultOnly: boolean, patches: readonly string[]): void {
const loaded = prepareProfile(profile, !defaultOnly)
export function runDumpConfig(
profile: string,
defaultOnly: boolean,
patches: readonly string[],
fromDefaultProfile?: string,
): void {
const loaded = prepareProfile(profile, !defaultOnly, fromDefaultProfile)
const userLayers: StackUserLayer[] = []
if (!defaultOnly) {
if (existsSync(loaded.patchPath)) {
+77 -5
View File
@@ -11,8 +11,8 @@
* @module @deepseek-ai/dsh/profile-boot
*/
import { writeFileSync } from 'node:fs'
import { join, resolve } from 'node:path'
import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
import { dirname, join, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { FiberState, type Context } from '@deepseek-ai/cordis'
import type { PatchOptions } from '@deepseek-ai/cordis-plugin-include'
@@ -22,13 +22,16 @@ import {
composeProfileStack,
formatRowConflict,
healProfilesModuleFallback,
initProfile,
installFailLoud,
installRuntimeGuards,
loadOptionalPatches,
loadOverlayPatches,
loadProfile,
PROFILE_PATCH_FILENAME,
PROFILE_TEMPLATES,
ProfileRuntime,
resolveProfileDir,
rootIncludeEntry,
warnNestedFiberFailures,
watchUserPatches,
@@ -94,6 +97,69 @@ const PROFILE_ROOT_CONFIG = `# dsh profile root — an empty entry list. The tre
/** Root config filename inside a profile directory. */
export const PROFILE_ROOT_FILENAME = 'cordis.yml'
/**
* Initialize a missing profile from one shipped template. This copies only
* the template's bundle list and patch-reload policy; local state from the
* same-named shipped profile is not read, and no inheritance metadata is
* persisted. Shipped profile names are reserved, and the target directory is
* claimed exclusively so existing or concurrent state is never reused.
* @param name - the new profile name.
* @param fromDefaultProfile - shipped profile template to copy.
* @param home - Harness home containing the profile directory.
* @throws when the template is unknown, the target name is shipped, or the target directory exists.
*/
export function initializeProfileFromDefault(
name: string,
fromDefaultProfile: string,
home: string = resolveDshHome(),
): void {
const dir = resolveProfileDir(name, home)
const template = Object.hasOwn(PROFILE_TEMPLATES, fromDefaultProfile)
? PROFILE_TEMPLATES[fromDefaultProfile]
: undefined
if (template === undefined) {
const expected = Object.keys(PROFILE_TEMPLATES).sort().map(value => JSON.stringify(value)).join(', ')
throw new Error(
`${NAME}: unknown default profile ${JSON.stringify(fromDefaultProfile)}; expected one of ${expected}`,
)
}
if (Object.hasOwn(PROFILE_TEMPLATES, name)) {
throw new Error(
`${NAME}: profile ${JSON.stringify(name)} is shipped and cannot be a custom profile target; `
+ 'omit --from-default-profile to use it',
)
}
mkdirSync(dirname(dir), { recursive: true })
try {
mkdirSync(dir)
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
const manifestPath = join(dir, 'package.json')
if (existsSync(manifestPath)) {
throw new Error(
`${NAME}: profile ${JSON.stringify(name)} already exists at ${manifestPath}; `
+ 'omit --from-default-profile to use it',
)
}
throw new Error(
`${NAME}: profile directory ${dir} already exists; choose an unused profile name`,
)
}
try {
initProfile(dir, template.bundles, template.patchReload)
} catch (error) {
try {
rmSync(dir, { recursive: true, force: true })
} catch (cleanupError) {
throw new AggregateError(
[error, cleanupError],
`${NAME}: profile initialization failed and ${dir} could not be removed`,
)
}
throw error
}
}
/**
* Resolve the telemetry opt-out switch into its boot patch. ANY non-empty
* value (including `'0'`/`'false'`) disables: a privacy switch prefers
@@ -121,9 +187,12 @@ export function resolveTelemetryPatch(disabledEnv: string | undefined, hasRow: b
* the identical base).
* @param name - the profile name.
* @param userLayer - `false` skips parsing `cordis.patch.yml` (the default dump).
* @param fromDefaultProfile - shipped template used once to initialize a missing profile.
* @returns the loaded profile.
* @throws when explicit initialization names an unknown template or an existing profile.
*/
export function prepareProfile(name: string, userLayer = true): Profile {
export function prepareProfile(name: string, userLayer = true, fromDefaultProfile?: string): Profile {
if (fromDefaultProfile !== undefined) initializeProfileFromDefault(name, fromDefaultProfile)
const profile = loadProfile(NAME, name, INSTALL_ANCHOR, undefined, { userLayer })
writeFileSync(join(profile.dir, PROFILE_ROOT_FILENAME), PROFILE_ROOT_CONFIG)
return profile
@@ -169,8 +238,9 @@ function userLayersOf(profile: Profile): StackUserLayer[] {
async function composeProfile(
name: string,
patchFiles: readonly string[],
fromDefaultProfile?: string,
): Promise<ComposedProfile> {
const profile = prepareProfile(name)
const profile = prepareProfile(name, true, fromDefaultProfile)
await healProfilesModuleFallback({ installAnchor: INSTALL_ANCHOR, profile })
const overlays: StackUserLayer[] = patchFiles.map(file => ({
label: `--patch ${resolve(file)}`, patches: loadOverlayPatches(NAME, resolve(file)),
@@ -194,6 +264,8 @@ export interface RunProfileOptions {
environment: LaunchEnvironmentSnapshot
/** The profile name to boot. */
profile: string
/** Shipped template used once to initialize a missing profile. */
fromDefaultProfile?: string | undefined
/** `--patch` overlay paths, in argv order. */
patchFiles: readonly string[]
/** The invocation's inner arguments, handed to the tree through `ctx.cmdlineArgs`. */
@@ -232,7 +304,7 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
(message) => { process.stderr.write(`${NAME}: ${message}\n`) },
)
const composed = await composeProfile(options.profile, options.patchFiles)
const composed = await composeProfile(options.profile, options.patchFiles, options.fromDefaultProfile)
const app: { current?: Context; runtime?: ProfileRuntime } = {}
const appReady = createAppReady()
let uninstallRuntimeGuards = (): void => {}