Merge master into feat/xdg-single-root-home

packages/sdk/create-sdk/package.json

@@ -13,10 +13,15 @@
     ".": {
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
     }
   },
   "files": [
     "lib/index.js",
+    "lib/invariant.js",
     "lib/bin.js",
     "lib/assets",
     "lib/types/**/*.d.ts",
@@ -29,9 +34,11 @@
     "commander": "^15.0.0"
   },
   "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }

packages/sdk/create-sdk/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/create-sdk`.
+ * @module @deepseek-ai/create-sdk/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/create-sdk'
+
+/** Cordis companion plugin name. */
+export const name = 'create-sdk-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this SDK build-time package owns no live event stream or mutable data;
+ * generated output and consumer tests cover its contract.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/sdk/create-sdk/tsconfig.json

@@ -6,7 +6,14 @@
   },
   "include": ["src"],
   "references": [
-    { "path": "../helper" },
-    { "path": "../../../vendor/cordis" }
+    {
+      "path": "../helper"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../support/invariants"
+    }
   ]
 }

packages/sdk/create-sdk/tsdown.config.ts

@@ -2,7 +2,7 @@ import { defineConfig } from 'tsdown'
 
 /** Bundle the library and create bin, then mirror package-owned terminal templates. */
 export default defineConfig({
-  entry: ['lib/types/index.js', 'lib/types/bin.js'],
+  entry: ['lib/types/index.js', 'lib/types/invariant.js', 'lib/types/bin.js'],
   outDir: 'lib',
   format: ['esm'],
   platform: 'node',

packages/sdk/helper/package.json

@@ -10,10 +10,15 @@
     ".": {
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
     }
   },
   "files": [
     "lib/index.js",
+    "lib/invariant.js",
     "lib/assets",
     "lib/types/**/*.d.ts",
     "lib/types/**/*.d.ts.map",
@@ -29,12 +34,14 @@
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-hooks-claude": "workspace:^",
     "@deepseek-ai/dsh-hooks-codex": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-sqlite": "workspace:^",
     "@deepseek-ai/dsh-tool-subagent": "workspace:^",

packages/sdk/helper/src/features/builtin/helpers.ts

@@ -15,8 +15,19 @@ import type {
   PackageScriptResource,
 } from '../resources.ts'
 
+/** Return the installable package name for a bare package or package subpath. */
+function installablePackageName(specifier: string): string {
+  const segments = specifier.split('/')
+  const expectedSegments = specifier.startsWith('@') ? 2 : 1
+  if (segments.length < expectedSegments || segments.slice(0, expectedSegments).some(segment => segment.length === 0)) {
+    throw new Error(`invalid bare package specifier: ${JSON.stringify(specifier)}`)
+  }
+  return segments.slice(0, expectedSegments).join('/')
+}
+
 /** Create a runtime NPM dependency resource. */
-function npmDependency(_owner: string, name: string): NpmDependencyResource {
+function npmDependency(_owner: string, specifier: string): NpmDependencyResource {
+  const name = installablePackageName(specifier)
   return {
     kind: 'npm-dependency',
     key: resourceKey(`npm-dependency:${name}`),
@@ -52,7 +63,7 @@ export function cordisConfigEntry(
   }
 }
 
-/** Couple one bare-package Cordis config entry to its mandatory runtime NPM dependency. */
+/** Couple one bare-package or subpath Cordis entry to its installable NPM package. */
 export function npmCordisConfigEntry(
   owner: string,
   value: CordisConfigEntry,

packages/sdk/helper/src/features/builtin/spine.ts

@@ -9,7 +9,7 @@ import type { ProjectProfile } from '../../project/types.ts'
 import { loadHelperTemplate } from '../../templates/template-assets.ts'
 import { FeatureOption, FixedFeature } from '../feature.ts'
 import { ProjectContribution } from '../resources.ts'
-import { npmCordisConfigEntry, requiredString } from './helpers.ts'
+import { cordisConfigEntry, npmCordisConfigEntry, requiredString } from './helpers.ts'
 
 const ID = featureId('spine')
 const PERSONA = loadHelperTemplate<Record<string, never>>('persona.txt.tpl').render({}).trimEnd()
@@ -37,6 +37,10 @@ class SpineOption extends FeatureOption {
       ...npmCordisConfigEntry(ID, { id: 'tools', name: '@deepseek-ai/dsh-tools' }, []),
       ...npmCordisConfigEntry(ID, { id: 'agent', name: '@deepseek-ai/dsh-agent' }),
       ...npmCordisConfigEntry(ID, { id: 'invariants', name: '@deepseek-ai/dsh-invariants' }),
+      cordisConfigEntry(ID, { id: 'session-invariant', name: '@deepseek-ai/dsh-session/invariant' }),
+      cordisConfigEntry(ID, { id: 'agent-invariant', name: '@deepseek-ai/dsh-agent/invariant' }),
+      ...npmCordisConfigEntry(ID, { id: 'scope-invariant', name: '@deepseek-ai/dsh-scope/invariant' }),
+      cordisConfigEntry(ID, { id: 'agent-loop-invariant', name: '@deepseek-ai/dsh-agent-loop/invariant' }),
       ...npmCordisConfigEntry(ID, {
         id: 'agent-loop',
         name: '@deepseek-ai/dsh-agent-loop',

packages/sdk/helper/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-helper`.
+ * @module @deepseek-ai/dsh-helper/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-helper'
+
+/** Cordis companion plugin name. */
+export const name = 'helper-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this SDK build-time package owns no live event stream or mutable data;
+ * generated output and consumer tests cover its contract.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/sdk/helper/tests/project.spec.ts

@@ -188,9 +188,15 @@ describe('SdkProject and ProjectEditSession', () => {
       .toContain('sessionId: !!js process.env.DSH_SDK_SESSION_ID')
     expect(project.cordis.entry('tui')?.config).not.toHaveProperty('model')
     expect(project.cordis.entry('agent-loop')?.config).toEqual({ agents: [] })
+    expect(project.cordis.entry('session-invariant')?.name).toBe('@deepseek-ai/dsh-session/invariant')
+    expect(project.cordis.entry('agent-invariant')?.name).toBe('@deepseek-ai/dsh-agent/invariant')
+    expect(project.cordis.entry('scope-invariant')?.name).toBe('@deepseek-ai/dsh-scope/invariant')
+    expect(project.cordis.entry('agent-loop-invariant')?.name).toBe('@deepseek-ai/dsh-agent-loop/invariant')
     expect(project.cordis.entry('system-prompt')?.config?.persona).toContain('{{cwd}}')
     expect(project.packageManifest().dependencies?.['@cordisjs/plugin-timer']).toBe('^1.1.2')
     expect(project.packageManifest().dependencies?.['@cordisjs/plugin-hmr']).toBe('^1.0.15')
+    expect(project.packageManifest().dependencies?.['@deepseek-ai/dsh-scope']).toBe('^0.0.1')
+    expect(project.packageManifest().dependencies).not.toHaveProperty('@deepseek-ai/dsh-scope/invariant')
     expect(project.packageManifest().dependencies).not.toHaveProperty('node-addon-require-builtin')
     expect(project.cordis.entry('hmr')).toMatchObject({ name: '@cordisjs/plugin-hmr' })
     expect(project.cordis.entry('llm-deepseek')?.config).not.toHaveProperty('baseURL')
@@ -888,6 +894,11 @@ describe('extension points', () => {
     expect(stringArray({ value: [1] }, 'value')).toHaveLength(1)
     expect(cordisConfigEntry('owner', { id: 'entry', name: 'pkg' }).ownedConfigKeys).toEqual([])
     expect(npmCordisConfigEntry('owner', { id: 'entry', name: 'pkg' })[1].ownedConfigKeys).toEqual([])
+    expect(npmCordisConfigEntry('owner', { id: 'entry', name: '@scope/pkg/subpath' })[0].name).toBe('@scope/pkg')
+    expect(npmCordisConfigEntry('owner', { id: 'entry', name: 'pkg/subpath' })[0].name).toBe('pkg')
+    for (const invalid of ['', '@scope', '@scope/']) {
+      expect(() => npmCordisConfigEntry('owner', { id: 'entry', name: invalid })).toThrow('invalid bare package specifier')
+    }
     expect(environmentResource('owner', 'EMPTY', undefined)).not.toHaveProperty('value')
     const builtins = createBuiltinRegistry(profile)
     expect(builtins.get(featureId('app')).defaultOptions(profile)).toEqual(['embed'])

packages/sdk/helper/tsconfig.json

@@ -6,14 +6,35 @@
   },
   "include": ["src"],
   "references": [
-    { "path": "../../util/brand" },
-    { "path": "../../compact/compact-basic" },
-    { "path": "../../hooks/hooks-claude" },
-    { "path": "../../hooks/hooks-codex" },
-    { "path": "../../session-persistence/session-persistence-jsonl" },
-    { "path": "../../session-persistence/session-persistence-sqlite" },
-    { "path": "../../subagent/tool-subagent" },
-    { "path": "../../web/tool-web" },
-    { "path": "../../../vendor/cordis" }
+    {
+      "path": "../../util/brand"
+    },
+    {
+      "path": "../../compact/compact-basic"
+    },
+    {
+      "path": "../../hooks/hooks-claude"
+    },
+    {
+      "path": "../../hooks/hooks-codex"
+    },
+    {
+      "path": "../../session-persistence/session-persistence-jsonl"
+    },
+    {
+      "path": "../../session-persistence/session-persistence-sqlite"
+    },
+    {
+      "path": "../../subagent/tool-subagent"
+    },
+    {
+      "path": "../../web/tool-web"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../support/invariants"
+    }
   ]
 }

packages/sdk/helper/tsdown.config.ts

@@ -2,7 +2,7 @@ import { defineConfig } from 'tsdown'
 
 /** Bundle helper runtime and mirror template assets beside the bundle. */
 export default defineConfig({
-  entry: ['lib/types/index.js'],
+  entry: ['lib/types/index.js', 'lib/types/invariant.js'],
   outDir: 'lib',
   format: ['esm'],
   platform: 'node',

packages/sdk/scripts/package.json

@@ -14,6 +14,10 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
     "./dev/tsdown-config": {
       "types": "./lib/types/dev/tsdown-config.d.ts",
       "default": "./lib/dev/tsdown-config.js"
@@ -21,6 +25,7 @@
   },
   "files": [
     "lib/index.js",
+    "lib/invariant.js",
     "lib/bin.js",
     "lib/dev/tsdown-config.js",
     "lib/local-plugin-loader-hooks.js",
@@ -38,16 +43,22 @@
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-app-boot": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
     "cordis": "^4.0.0-rc.7",
     "tsdown": "^0.22.2",
     "tsx": "^4.22.4"
   },
   "peerDependenciesMeta": {
-    "tsdown": { "optional": true },
-    "tsx": { "optional": true }
+    "tsdown": {
+      "optional": true
+    },
+    "tsx": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@deepseek-ai/dsh-app-boot": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
     "cordis": "^4.0.0-rc.7",
     "tsdown": "^0.22.2",
     "tsx": "^4.22.4"

packages/sdk/scripts/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-scripts`.
+ * @module @deepseek-ai/dsh-scripts/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-scripts'
+
+/** Cordis companion plugin name. */
+export const name = 'scripts-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this SDK build-time package owns no live event stream or mutable data;
+ * generated output and consumer tests cover its contract.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/sdk/scripts/tests/scripts.spec.ts

@@ -135,6 +135,7 @@ describe('Commander launcher arguments', () => {
     expect(parseDshSdkArgs(['start'])).toEqual({ command: 'start', forwarded: [], help: false })
     expect(parseDshSdkArgs(['dev', 'index.ts'])).toMatchObject({ command: 'dev', target: 'index.ts' })
     expect(parseDshSdkArgs(['-h'])).toMatchObject({ help: true })
+    expect(parseDshSdkArgs(['--help'])).toMatchObject({ help: true })
     expect(() => parseDshSdkArgs(['unknown'])).toThrow()
     expect(() => parseDshSdkArgs(['config', 'extra'])).toThrow()
     expect(() => parseDshSdkArgs(['config', '--', 'extra'])).toThrow('does not accept forwarded')

packages/sdk/scripts/tsconfig.json

@@ -9,6 +9,7 @@
     { "path": "../helper" },
     { "path": "../telemetry" },
     { "path": "../../ui/app-boot" },
-    { "path": "../../../vendor/cordis" }
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../support/invariants" }
   ]
 }

packages/sdk/scripts/tsdown.config.ts

@@ -7,6 +7,10 @@ export default defineConfig([
     fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
     copy: [{ from: 'src/templates/assets/*', to: 'lib/assets' }],
   },
+  {
+    entry: ['lib/types/invariant.js'], outDir: 'lib', format: ['esm'], platform: 'node', target: 'es2024',
+    fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
+  },
   {
     entry: ['lib/types/bin.js'], outDir: 'lib', format: ['esm'], platform: 'node', target: 'es2024',
     fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,

packages/sdk/telemetry/package.json

@@ -11,11 +11,16 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
+    "lib/invariant.js",
     "lib/types/**/*.d.ts",
     "lib/types/**/*.d.ts.map",
     "src"
@@ -26,11 +31,13 @@
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-paths": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-paths": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }

packages/sdk/telemetry/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-telemetry`.
+ * @module @deepseek-ai/dsh-telemetry/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-telemetry'
+
+/** Cordis companion plugin name. */
+export const name = 'telemetry-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this SDK build-time package owns no live event stream or mutable data;
+ * generated output and consumer tests cover its contract.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/sdk/telemetry/tsconfig.json

@@ -9,6 +9,7 @@
   ],
   "references": [
     { "path": "../../util/brand" },
-    { "path": "../../util/paths" }
+    { "path": "../../util/paths" },
+    { "path": "../../support/invariants" }
   ]
 }