@dsh-workbench/shared 0.3.11 → 1.0.0-beta.0

package/src/contract/protocol/dsh-plugins.ts

@@ -0,0 +1,13 @@
+export const DSH_PLUGINS_ROUTE = 'dsh-plugins';
+
+export interface DshPluginRow {
+  readonly name: string;
+  readonly version: string;
+  readonly enabled: boolean;
+}
+
+export interface DshPluginsSnapshot {
+  readonly available: boolean;
+  readonly bundles: readonly DshPluginRow[];
+  readonly plugins: readonly DshPluginRow[];
+}

package/src/contract/protocol/long-tasks.ts

@@ -0,0 +1,16 @@
+import type { LongTaskStatus } from '../long-task.js';
+
+export const LONG_TASKS_ROUTE = 'long-tasks';
+
+export interface ShellLongTaskRow {
+  readonly unit: string;
+  readonly id: string;
+  readonly workspace: string;
+  readonly target: string;
+  readonly status: LongTaskStatus;
+  readonly session?: string | undefined;
+}
+
+export interface ShellLongTasksPayload {
+  readonly runs: readonly ShellLongTaskRow[];
+}

package/src/contract/protocol/market-index.ts

@@ -0,0 +1,246 @@
+export const MARKET_INDEX_FORMAT = 1;
+export const MARKET_INDEX_PATH = 'market.json';
+export const MARKET_DISCOVER_ROUTE = 'panels/market-discover';
+export const MARKET_DOC_ROUTE = 'panels/market-doc';
+export const MARKET_PUBLISH_PREVIEW_ROUTE = 'panels/market-publish-preview';
+export const MARKET_SOURCES_RESOURCE = 'market-sources';
+export const MARKET_WORKBENCH_LABEL = 'workbench';
+
+export type MarketSourceKind = 'http' | 'git';
+
+export type MarketSourcePolicy = 'artifacts-in-repo' | 'catalog-only';
+
+export interface IndexSourceSpec {
+  readonly kind: MarketSourceKind;
+  readonly url: string;
+  readonly ref?: string;
+  readonly path?: string;
+  readonly localPath?: string;
+}
+
+export interface MarketSourceConfig extends IndexSourceSpec {
+  readonly id: string;
+  readonly label: string;
+  readonly policy?: MarketSourcePolicy;
+}
+
+export interface MarketLocalizedText {
+  readonly zh?: string;
+  readonly en?: string;
+}
+
+export interface MarketIndexNpmSource {
+  readonly type: 'npm';
+  readonly registry?: string;
+}
+
+export interface MarketIndexGitSource {
+  readonly type: 'git';
+  readonly url: string;
+  readonly commit: string;
+  readonly path?: string;
+}
+
+export type MarketIndexSource = MarketIndexNpmSource | MarketIndexGitSource;
+
+export interface MarketIndexEngines {
+  readonly dsh?: string;
+}
+
+export interface MarketIndexVersion {
+  readonly version: string;
+  readonly publishTimestamp?: number;
+  readonly source: MarketIndexSource;
+  readonly engines?: MarketIndexEngines;
+}
+
+export interface MarketIndexEntryMetadata {
+  readonly category?: string;
+  readonly labels?: readonly string[];
+  readonly keywords?: readonly string[];
+  readonly sortKeys?: Readonly<Record<string, string | number>>;
+}
+
+export interface MarketIndexEntry {
+  readonly name: string;
+  readonly title?: MarketLocalizedText;
+  readonly description?: MarketLocalizedText;
+  readonly author?: string;
+  readonly homepage?: string;
+  readonly icon?: string;
+  readonly metadata?: MarketIndexEntryMetadata;
+  readonly versions: readonly MarketIndexVersion[];
+}
+
+export interface MarketIndexCategory {
+  readonly title?: MarketLocalizedText;
+}
+
+export interface MarketIndexLabel {
+  readonly title?: MarketLocalizedText;
+}
+
+export interface MarketIndexSortKey {
+  readonly title?: MarketLocalizedText;
+  readonly order?: 'asc' | 'desc';
+}
+
+export interface MarketIndexMetadata {
+  readonly categories?: Readonly<Record<string, MarketIndexCategory>>;
+  readonly labels?: Readonly<Record<string, MarketIndexLabel>>;
+  readonly sortKeys?: Readonly<Record<string, MarketIndexSortKey>>;
+}
+
+export interface MarketIndex {
+  readonly format: 1;
+  readonly title?: MarketLocalizedText;
+  readonly description?: MarketLocalizedText;
+  readonly metadata?: MarketIndexMetadata;
+  readonly plugins: readonly MarketIndexEntry[];
+}
+
+export type MarketIndexProblemKind =
+  | 'not-json'
+  | 'not-object'
+  | 'format'
+  | 'plugins'
+  | 'plugin'
+  | 'name'
+  | 'duplicate-name'
+  | 'versions'
+  | 'version'
+  | 'version-order'
+  | 'source'
+  | 'git-commit'
+  | 'timestamp'
+  | 'icon';
+
+export interface MarketIndexProblem {
+  readonly kind: MarketIndexProblemKind;
+  readonly detail: string;
+  readonly at?: string;
+}
+
+export type MarketIndexParse =
+  | { readonly ok: true; readonly index: MarketIndex }
+  | { readonly ok: false; readonly problems: readonly MarketIndexProblem[] };
+
+export type DiscoverCompat = 'ok' | 'incompatible' | 'unknown';
+
+export type DiscoverInstallState = 'not-installed' | 'installed' | 'update-available' | 'different-version';
+
+export interface DiscoverVersionRow {
+  readonly version: string;
+  readonly publishTimestamp?: number;
+  readonly source: MarketIndexSource;
+  readonly engines?: MarketIndexEngines;
+  readonly compat: DiscoverCompat;
+  readonly peer?: string;
+  readonly install: DiscoverInstallState;
+}
+
+export interface DiscoverEntry {
+  readonly name: string;
+  readonly title?: MarketLocalizedText;
+  readonly description?: MarketLocalizedText;
+  readonly author?: string;
+  readonly homepage?: string;
+  readonly icon?: string;
+  readonly category?: string;
+  readonly labels: readonly string[];
+  readonly installedVersion?: string;
+  readonly versions: readonly DiscoverVersionRow[];
+}
+
+export interface DiscoverSourceRow extends MarketSourceConfig {
+  readonly writable: boolean | null;
+}
+
+export type DiscoverState = 'no-source' | 'ready' | 'unreadable' | 'invalid';
+
+export interface DiscoverProblem {
+  readonly kind:
+    | 'no-source'
+    | 'http-status'
+    | 'http-network'
+    | 'http-url'
+    | 'git-missing'
+    | 'git-network'
+    | 'git-auth'
+    | 'git-file'
+    | 'git-empty'
+    | 'git-missing-index'
+    | 'format'
+    | 'timeout'
+    | 'unknown';
+  readonly detail?: string;
+  readonly branch?: string;
+}
+
+export interface DiscoverPayload {
+  readonly state: DiscoverState;
+  readonly sources: readonly DiscoverSourceRow[];
+  readonly selected: string | null;
+  readonly entries: readonly DiscoverEntry[];
+  readonly fetchedAt?: number;
+  readonly commit?: string;
+  readonly stale?: boolean;
+  readonly problem?: DiscoverProblem;
+}
+
+export interface DiscoverFilter {
+  readonly query?: string;
+  readonly category?: string;
+  readonly label?: string;
+}
+
+export interface MarketSourcesPayload {
+  readonly sources: readonly MarketSourceConfig[];
+  readonly selected: string | null;
+}
+
+export interface MarketPublishDestination {
+  readonly url: string;
+  readonly ref?: string;
+  readonly indexPath: string;
+  readonly artifactPath: string;
+  readonly files: readonly string[];
+  readonly nextVersion?: string;
+}
+
+export interface PublishChangelog {
+  readonly version: string;
+  readonly text?: string;
+  readonly missing?: boolean;
+}
+
+export interface PublishPreview {
+  readonly name: string;
+  readonly version: string;
+  readonly registry?: string;
+  readonly market?: MarketPublishDestination;
+  readonly changelog?: PublishChangelog;
+}
+
+export type DiscoverDocKind = 'readme' | 'changelog';
+
+export type DiscoverDoc =
+  | {
+      readonly ok: true;
+      readonly kind: DiscoverDocKind;
+      readonly version: string;
+      readonly text: string;
+    }
+  | {
+      readonly ok: false;
+      readonly kind: DiscoverDocKind;
+      readonly version: string;
+      readonly reason: 'missing' | 'unavailable';
+      readonly detail?: string;
+    };
+
+export type MarketSourcesAction =
+  | { readonly action: 'save'; readonly source: MarketSourceConfig; readonly select?: boolean }
+  | { readonly action: 'remove'; readonly id: string }
+  | { readonly action: 'select'; readonly id: string | null }
+  | { readonly action: 'init'; readonly id: string; readonly ref?: string };

package/src/contract/protocol/platform.ts

@@ -0,0 +1,47 @@
+export type Deployment = 'web' | 'desktop';
+
+export type HostOs = 'darwin' | 'win32' | 'linux' | 'other';
+
+export type HostRuntime = 'electron' | 'node';
+
+export type ClientShell = 'electron' | 'browser';
+
+export type ProfileName = 'desktop' | 'web' | 'workbench' | 'headless' | 'other';
+
+export type SelfUpdateCli = 'path-dsh' | 'desktop-cli';
+
+export interface HostCapabilities {
+  readonly pageDebug: boolean;
+  readonly siteExplore: boolean;
+  readonly recording: boolean;
+  readonly browserWake: boolean;
+  readonly selfUpdateCli: SelfUpdateCli;
+  readonly safeMode: boolean;
+}
+
+export interface ToolchainPlan {
+  readonly node: { readonly source: 'desktop-shim' | 'path' };
+  readonly npm: { readonly neededFor: 'opencli-install' };
+  readonly pnpm: { readonly neededFor: 'workshop'; readonly expectedMajor: 10 };
+}
+
+export interface HostSurface {
+  readonly deployment: Deployment;
+  readonly hostOs: HostOs;
+  readonly runtime: HostRuntime;
+  readonly profile: ProfileName;
+  readonly capabilities: HostCapabilities;
+  readonly restartHint: string;
+  readonly toolchain: ToolchainPlan;
+}
+
+export interface ClientCapabilities {
+  readonly debugFooter: boolean;
+}
+
+export interface ClientSurface {
+  readonly deployment: Deployment;
+  readonly shell: ClientShell;
+  readonly hostOs: HostOs;
+  readonly capabilities: ClientCapabilities;
+}

package/src/contract/protocol/preflight-wake.ts

@@ -0,0 +1,17 @@
+export const WAKE_BROWSER_ROUTE = 'wake-browser';
+
+export type DesktopBrowserId = 'chrome' | 'edge' | 'brave' | 'chromium' | 'vivaldi';
+
+export type BrowserWakeStatus =
+  | 'connected'
+  | 'browser-open'
+  | 'no-browser'
+  | 'launch-failed'
+  | 'not-connected'
+  | 'unsupported'
+  | 'unknown';
+
+export interface WakeBrowserReply {
+  readonly status: BrowserWakeStatus;
+  readonly browser?: DesktopBrowserId;
+}

package/src/contract/protocol/profile-create.ts

@@ -0,0 +1,36 @@
+export const PROFILE_CREATE_ROUTE = 'profile-create';
+
+export const PROFILE_CREATE_RESOURCE = 'profileCreate';
+
+export interface ProfileCreateProfile {
+  readonly name: string;
+  readonly current: boolean;
+  readonly readable: boolean;
+}
+
+export interface ProfileCreateSnapshot {
+  readonly current: string;
+  readonly profiles: readonly ProfileCreateProfile[];
+}
+
+export interface ProfileCreateCopy {
+  readonly settings: boolean;
+  readonly plugins: boolean;
+  readonly projects: boolean;
+  readonly sessions: boolean;
+}
+
+export interface ProfileCreateRequest {
+  readonly profile: string;
+  readonly source: string;
+  readonly copy: ProfileCreateCopy;
+}
+
+export interface ProfileCreateApplied {
+  readonly ok: true;
+  readonly profile: string;
+  readonly source: string;
+  readonly home: string;
+  readonly command: string;
+  readonly copied: readonly string[];
+}

package/src/contract/protocol/sidebar-edition.ts

@@ -0,0 +1,19 @@
+export const SIDEBAR_EDITION_ROUTE = 'sidebar-edition';
+
+export const SIDEBAR_EDITION_RESOURCE = 'sidebarEdition';
+
+export type SidebarEdition = 'official' | 'custom';
+
+export interface SidebarEditionSnapshot {
+  readonly edition: SidebarEdition;
+}
+
+export interface SidebarEditionApplied {
+  readonly ok: true;
+  readonly edition: SidebarEdition;
+  readonly reloadRequired: boolean;
+}
+
+export interface SidebarEditionRequest {
+  readonly edition: SidebarEdition;
+}

package/src/contract/protocol/unit-manifests.ts

@@ -0,0 +1,8 @@
+import type { UnitManifest } from '../unit.js';
+
+export const UNIT_MANIFESTS_ROUTE = 'unit-manifests';
+
+export interface UnitManifestsPayload {
+  readonly manifests: readonly UnitManifest[];
+  readonly installable: readonly string[];
+}

package/src/{api → contract}/unit-board.ts

@@ -21,4 +21,3 @@ export interface UnitBlockers {
   readonly blocker?: ModuleBlocker;
   readonly notice?: ModuleBlocker;
 }
-

package/src/contract/unit-capability.ts

@@ -0,0 +1,37 @@
+import type { Need, NeedKind } from './needs.js';
+import type { ProvisionProblem } from './plugin-source.js';
+
+/**
+ * 一条 need 探出来的样子：状态、给人看的一句、以及能照做的修法。
+ */
+export interface NeedState {
+  readonly id: string;
+  readonly kind: NeedKind;
+  readonly name: string;
+  readonly status: 'ok' | 'missing' | 'outdated' | 'unsatisfied' | 'unchecked';
+  readonly detail: string;
+  readonly command?: string;
+  readonly missing?: readonly string[];
+  readonly installed?: string;
+  readonly latest?: string;
+  readonly provision?: 'ready' | ProvisionProblem;
+}
+
+/**
+ * 一个单元的能力结论：unit 一级只做汇总，缺什么逐条看 needs。
+ */
+export interface UnitCapability {
+  readonly unit: string;
+  readonly status: 'ok' | 'degraded' | 'missing' | 'outdated' | 'unchecked' | 'unsupported' | 'failed';
+  readonly needs: readonly NeedState[];
+  readonly detail?: string;
+  readonly released?: boolean;
+}
+
+/**
+ * 探一个单元的输入：单元 id 加它声明的 need 列表。
+ */
+export interface NeedProbeInput {
+  readonly unit: string;
+  readonly needs: readonly Need[];
+}

package/src/{host → contract}/unit-declaration.ts

@@ -1,9 +1,10 @@
-import type { UnitEnvNeeds, UnitHostNeeds, UnitManifest } from '../api/unit.js';
+import type { UnitHostNeeds, UnitManifest } from '../contract/unit.js';
+import { needsProblemsOf, type Need } from './needs.js';
 
 /**
  * 声明协议当前版本；模块清单的 dsh.workbench.apiVersion 要写这个整数。
  */
-export const WORKBENCH_API_VERSION = 1;
+export const WORKBENCH_API_VERSION = 2;
 
 /**
  * 外壳愿意认的协议版本；不在表里的模块当场被拒，不猜语义。
@@ -36,11 +37,11 @@ export interface UnitDeclaration {
   readonly card: UnitCardDeclaration | null;
   readonly tools: readonly UnitToolDeclaration[];
   readonly host: UnitHostNeeds;
-  readonly env?: UnitEnvNeeds;
+  readonly needs?: readonly Need[];
 }
 
 /**
- * 协议认得的全部键；写了别的键不会被采纳（外壳静默忽略），所以字段名拼错不会有提示。
+ * 协议认得的全部键；写了别的键这份清单会被拒（`protocol` 判据与运行时同一套），拼错当场报出来。
  */
 export const DECLARATION_KEYS: readonly string[] = [
   'apiVersion',
@@ -48,11 +49,11 @@ export const DECLARATION_KEYS: readonly string[] = [
   'card',
   'tools',
   'host',
-  'env',
+  'needs',
 ];
 
 /**
- * 协议要求必写的键；env 不在其中（没有环境需要就不写）。
+ * 协议要求必写的键；needs 不在其中（没有环境需要就不写）。
  */
 export const DECLARATION_REQUIRED_KEYS: readonly string[] = [
   'apiVersion',
@@ -104,13 +105,19 @@ export function declarationProblemsOf(subject: string, raw: unknown): readonly s
   if (version === undefined) {
     return [
       `${subject}: dsh.workbench 没有 apiVersion —— 协议从 v${WORKBENCH_API_VERSION} 起，` +
-        `写 \`"apiVersion": ${WORKBENCH_API_VERSION}\`。缺它 = 外壳不认这个模块（ADR-0038 §2.3）`,
+        `写 \`"apiVersion": ${WORKBENCH_API_VERSION}\`。缺它 = 外壳不认这个模块`,
     ];
   }
   if (!Number.isInteger(version) || !SUPPORTED_API_VERSIONS.includes(version as number)) {
+    const hint =
+      version === 1
+        ? ` —— v2 把 \`env\` 的三张表（command / plugins / libs）换成了 \`needs\`：` +
+          '把外部需要逐条写成 `{ kind, name, purpose, ... }`（kind 是 bin / extension / lib / env），' +
+          '再把 apiVersion 改成 2'
+        : '';
     return [
       `${subject}: dsh.workbench.apiVersion 是 ${JSON.stringify(version)}，这里只认 ` +
-        `${SUPPORTED_API_VERSIONS.join(' / ')}（要整数）`,
+        `${SUPPORTED_API_VERSIONS.join(' / ')}（要整数）${hint}`,
     ];
   }
 
@@ -120,7 +127,7 @@ export function declarationProblemsOf(subject: string, raw: unknown): readonly s
   if (unknown.length > 0) {
     problems.push(
       `${subject}: dsh.workbench 里有协议 v${WORKBENCH_API_VERSION} 不认识的键 ${listOf(unknown)} —— ` +
-        `只有 ${listOf(DECLARATION_KEYS)}。（拼错的键会被外壳**静默忽略**：那句声明等于没写）`,
+        `只有 ${listOf(DECLARATION_KEYS)}。（协议外的键会让这份清单被拒：那句声明等于没写）`,
     );
   }
 
@@ -224,13 +231,6 @@ export function declarationProblemsOf(subject: string, raw: unknown): readonly s
     }
   }
 
-  if (raw.env !== undefined && !isRecord(raw.env)) {
-    problems.push(
-      `${subject}: dsh.workbench.env 要是对象（command / plugins / libs）—— ` +
-        `语义由门禁的 env 判据查，这里只查形状`,
-    );
-  }
-
   return problems;
 }
 
@@ -241,6 +241,7 @@ export interface DeclarationRead {
   readonly declaration?: UnitDeclaration;
   readonly manifest?: UnitManifest;
   readonly problems: readonly string[];
+  readonly warnings: readonly string[];
 }
 
 /**
@@ -251,8 +252,10 @@ export interface DeclarationRead {
  */
 export function readDeclaration(subject: string, raw: unknown): DeclarationRead {
   const problems = declarationProblemsOf(subject, raw);
-  if (problems.length > 0) return { problems };
+  if (problems.length > 0) return { problems, warnings: [] };
   const declaration = raw as UnitDeclaration;
+  const needsRead = needsProblemsOf(subject, declaration.needs);
+  if (needsRead.errors.length > 0) return { problems: needsRead.errors, warnings: needsRead.warnings };
   const card = declaration.card;
   return {
     declaration,
@@ -274,7 +277,8 @@ export function readDeclaration(subject: string, raw: unknown): DeclarationRead
         inject: [...(declaration.host.inject ?? [])],
         ...(declaration.host.optional === undefined ? {} : { optional: [...declaration.host.optional] }),
       },
-      ...(declaration.env === undefined ? {} : { env: declaration.env }),
+      ...(declaration.needs === undefined ? {} : { needs: declaration.needs }),
     },
+    warnings: needsRead.warnings,
   };
 }

package/src/contract/unit.ts

@@ -0,0 +1,76 @@
+import type { ExtensionNeed, LibNeed, Need } from './needs.js';
+
+/**
+ * 一张卡片在清单里的静态声明（文案键加排序位）；默认显不显示由运行期面板配置定。
+ */
+export interface UnitCard {
+  readonly titleKey: string;
+  readonly order: number;
+}
+
+/**
+ * 一条工具在清单里的样子：全名加会不会写；审批按 writes 认领。
+ */
+export interface UnitTool {
+  readonly name: string;
+  readonly writes: boolean;
+}
+
+/**
+ * 模块要外壳的哪些服务：inject 缺一个就挂不上，optional 缺了照挂。
+ */
+export interface UnitHostNeeds {
+  readonly inject: readonly string[];
+  readonly optional?: readonly string[];
+}
+
+/**
+ * 已装插件与源上最新版那一对，用来判该不该提示升级；latest 缺省表示还没查到。
+ */
+export interface PluginRelease {
+  readonly installed: string;
+  readonly latest?: string;
+}
+
+/**
+ * 装配期用的模块清单：单元 id、卡片、工具、宿主服务与环境需要，比声明少一层协议包装。
+ */
+export interface UnitManifest {
+  readonly id: string;
+  readonly card: UnitCard | null;
+  readonly tools: readonly UnitTool[];
+  readonly host: UnitHostNeeds;
+  readonly needs?: readonly Need[];
+}
+
+/**
+ * 模块声明的全部环境需要（没写就是空表）。
+ * @param manifest 模块清单。
+ * @returns need 列表。
+ */
+export function needsOf(manifest: UnitManifest): readonly Need[] {
+  return manifest.needs ?? [];
+}
+
+/**
+ * 宿主能代装的那些需要：只有写了 `sources` 的 extension / lib 算。
+ * @param manifest 模块清单。
+ * @returns 可代装的 need 列表。
+ */
+export function provisionableNeedsOf(manifest: UnitManifest): readonly (ExtensionNeed | LibNeed)[] {
+  return needsOf(manifest).filter(
+    (need): need is ExtensionNeed | LibNeed =>
+      (need.kind === 'extension' || need.kind === 'lib') && (need.sources ?? []).length > 0,
+  );
+}
+
+/**
+ * 市场门槛要看的那些需要：声明了 extension / lib 就算（不要求写了来源）。
+ * @param manifest 模块清单。
+ * @returns extension / lib 的 need 列表。
+ */
+export function supplyNeedsOf(manifest: UnitManifest): readonly (ExtensionNeed | LibNeed)[] {
+  return needsOf(manifest).filter(
+    (need): need is ExtensionNeed | LibNeed => need.kind === 'extension' || need.kind === 'lib',
+  );
+}

package/src/contract/workbench-contract.ts

@@ -0,0 +1,30 @@
+import type { NeedState } from '../contract/unit-capability.js';
+
+/**
+ * 供给动作的那几档（装 / 升 / 卸，模块、共用依赖与插件各一套）；写口按它分派。
+ */
+export type ProvisionAction =
+  | 'install'
+  | 'update'
+  | 'uninstall'
+  | 'update-dependency'
+  | 'install-bundle'
+  | 'install-version'
+  | 'update-bundle'
+  | 'remove-bundle'
+  | 'cancel-install'
+  | 'update-plugin'
+  | 'uninstall-plugin'
+  | 'update-workbench';
+
+/**
+ * 宿主对「这个单元现在能不能用」的那份读数：状态汇总加逐条 need 的细节。
+ */
+export interface CapabilityPayload {
+  readonly unit: string;
+  readonly status: 'ok' | 'degraded' | 'missing' | 'outdated' | 'unchecked' | 'unsupported' | 'failed';
+  readonly needs: readonly NeedState[];
+  readonly detail?: string;
+  readonly released?: boolean;
+}
+