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

package/src/contract/protocol/bundle-install.ts

@@ -0,0 +1,198 @@
+export const BUNDLE_REGISTRIES_ROUTE = 'bundle-registries';
+
+export const BUNDLE_INSPECT_ROUTE = 'bundle-inspect';
+
+export const BUNDLE_REGISTRY_DEFAULT = 'default';
+export const MODULE_VERSIONS_ROUTE = 'module-versions';
+
+export type BundleRegistry = string | null;
+
+export interface BundleRegistries {
+  readonly registry: BundleRegistry;
+  readonly fallbackRegistries: readonly BundleRegistry[];
+  readonly resolved: string | null;
+}
+
+export type BundleInspectProblem =
+  | 'invalid-spec'
+  | 'already-installed'
+  | 'not-found'
+  | 'not-a-package'
+  | 'not-a-bundle'
+  | 'not-a-workbench-module'
+  | 'not-a-module-or-plugin'
+  | 'network'
+  | 'unknown';
+
+export type BundleSpecKind = 'registry' | 'path' | 'git' | 'tarball';
+
+export interface BundleInspectionAccepted {
+  readonly status: 'accepted';
+  readonly kind: BundleSpecKind;
+  readonly name?: string;
+  readonly version?: string;
+  readonly description?: string;
+  readonly bundle: boolean | null;
+  readonly registry: BundleRegistry;
+  readonly host?: string;
+}
+
+export interface BundleInspectionRefused {
+  readonly status: 'refused';
+  readonly problem: BundleInspectProblem;
+  readonly reason: string;
+  readonly registries?: readonly BundleRegistry[];
+}
+
+export interface BundleInspectionPlugin {
+  readonly status: 'plugin';
+  readonly pkg: string;
+  readonly registry: BundleRegistry;
+  readonly pluginName?: string;
+  readonly version?: string;
+}
+
+export type BundleInspection =
+  | BundleInspectionAccepted
+  | BundleInspectionRefused
+  | BundleInspectionPlugin;
+
+export interface BundleRegistriesPayload {
+  readonly available: boolean;
+  readonly registries: BundleRegistries | null;
+}
+
+export interface BundleInspectionPayload {
+  readonly inspection: BundleInspection;
+}
+
+export type BundleApplication = 'applied' | 'restart-required' | 'overridden' | 'failed' | 'cancelled';
+
+export const SELF_UPDATE_STATES = ['running', 'ok', 'rolled-back', 'failed'] as const;
+
+export type SelfUpdateState = (typeof SELF_UPDATE_STATES)[number];
+
+export interface WorkbenchSelfUpdate {
+  readonly state: SelfUpdateState;
+  readonly profile?: string;
+  readonly from?: string;
+  readonly to?: string;
+  readonly version?: string;
+  readonly at?: string;
+  readonly tail?: string;
+}
+
+export const RESTART_REASONS = [
+  'no-hmr',
+  'package-moved',
+  'host-module',
+  'unmanaged-plugin',
+  'module-comparison',
+] as const;
+
+export type RestartReason = (typeof RESTART_REASONS)[number];
+
+export type BundleChangeStage = 'install' | 'enable' | 'remove';
+
+export type BundleFailureKind =
+  | 'pnpm-missing'
+  | 'timeout'
+  | 'not-found'
+  | 'no-matching-version'
+  | 'network'
+  | 'disk-full'
+  | 'permission'
+  | 'build-blocked'
+  | 'integrity'
+  | 'unknown';
+
+export interface BundlePackageResult {
+  readonly exitCode: number;
+  readonly output: string;
+  readonly truncated: boolean;
+  readonly logPath: string;
+  readonly kind?: BundleFailureKind;
+}
+
+export interface BundleChange {
+  readonly application: BundleApplication;
+  readonly stage: BundleChangeStage;
+  readonly changed: boolean;
+  readonly target: string;
+  readonly bundle?: string;
+  readonly version?: string;
+  readonly errorCode?: string;
+  readonly errorDetail?: string;
+  readonly packageResult?: BundlePackageResult;
+  readonly pendingBuilds?: readonly string[];
+  readonly restartReason?: RestartReason;
+  readonly failedAt?: 'registry' | 'spec-host';
+}
+
+export interface BundleInstallRequest {
+  readonly spec: string;
+  readonly registry?: BundleRegistry;
+  readonly requestId?: string;
+  readonly approvedBuilds?: readonly string[];
+}
+
+export type BundleCancellation = 'cancelled' | 'too-late' | 'not-running';
+
+export type BundleSupplyState = 'not-a-module' | 'no-needs' | 'installed' | 'failed' | 'pending-restart';
+
+export interface BundleModulePayload {
+  readonly kind: 'module' | 'not-module' | 'unknown';
+  readonly pkg: string;
+  readonly unit?: string;
+  readonly version?: string;
+}
+
+export interface BundleSupplyPayload {
+  readonly state: BundleSupplyState;
+  readonly reason?: string;
+}
+
+export interface BundleInstalledPlugin {
+  readonly kind: 'opencli-plugin';
+  readonly pkg: string;
+  readonly name?: string;
+}
+
+export interface BundleInstallPayload {
+  readonly change: BundleChange;
+  readonly module: BundleModulePayload;
+  readonly supply: BundleSupplyPayload;
+  readonly plugin?: BundleInstalledPlugin;
+}
+
+export interface BundleRemovePayload {
+  readonly change: BundleChange;
+  readonly keptFor: readonly string[];
+}
+
+export interface BundleCancellationPayload {
+  readonly cancellation: BundleCancellation | null;
+}
+
+export interface ModuleVersion {
+  readonly unit: string;
+  readonly pkg: string;
+  readonly installed: string;
+  readonly latest?: string;
+  readonly local?: boolean;
+  readonly refused?: readonly string[];
+}
+
+export interface WorkbenchVersion {
+  readonly pkg: string;
+  readonly installed: string;
+  readonly latest?: string;
+  readonly running?: string;
+  readonly local?: boolean;
+}
+
+export interface ModuleVersionsPayload {
+  readonly modules: readonly ModuleVersion[];
+  readonly workbench?: WorkbenchVersion;
+  readonly selfUpdate?: WorkbenchSelfUpdate;
+}

package/src/contract/protocol/config-sync.ts

@@ -0,0 +1,65 @@
+export const CONFIG_SYNC_ROUTE = 'config-sync';
+
+export const CONFIG_SYNC_RESOURCE = 'configSync';
+
+export type ConfigSyncState = 'new' | 'differs' | 'same';
+
+export type ConfigSyncAssetState = 'missing' | 'differs' | 'same' | 'external';
+
+export interface ConfigSyncAssetFile {
+  readonly path: string;
+  readonly state: ConfigSyncAssetState;
+  readonly bytes: number | null;
+}
+
+export interface ConfigSyncAsset {
+  readonly key: string;
+  readonly path: string;
+  readonly kind: 'file' | 'dir';
+  readonly state: ConfigSyncAssetState;
+  readonly files: readonly ConfigSyncAssetFile[];
+  readonly bytes: number;
+  readonly reason?: string;
+}
+
+export interface ConfigSyncRow {
+  readonly key: string;
+  readonly id: string;
+  readonly insert: boolean;
+  readonly state: ConfigSyncState;
+  readonly body: string;
+  readonly ownBody: string | null;
+  readonly missing: readonly string[];
+  readonly assets: readonly ConfigSyncAsset[];
+}
+
+export interface ConfigSyncProfile {
+  readonly name: string;
+  readonly readable: boolean;
+  readonly candidates: number;
+}
+
+export interface ConfigSyncSnapshot {
+  readonly self: string;
+  readonly home: string;
+  readonly source: string;
+  readonly profiles: readonly ConfigSyncProfile[];
+  readonly rows: readonly ConfigSyncRow[];
+  readonly emptyProviders: boolean;
+  readonly reason?: string;
+}
+
+export interface ConfigSyncApplied {
+  readonly written: readonly string[];
+  readonly skipped: readonly string[];
+  readonly files: readonly string[];
+  readonly verified: boolean;
+}
+
+export interface ConfigSyncRequest {
+  readonly source: string;
+  readonly keys: readonly string[];
+  readonly overwrite: readonly string[];
+  readonly assets?: readonly string[];
+  readonly overwriteAssets?: readonly string[];
+}

package/src/contract/protocol/diy.ts

@@ -0,0 +1,4 @@
+export const DIY_PRESET_ID = 'workbench-diy';
+export const WORKSHOP_RELATIVE = 'workbench/diy';
+export const WORKSHOP_TITLE = '工作台DIY';
+export const WORKSHOP_PAST_TITLES: readonly string[] = ['DIY 工坊', '工作台自带 · DIY 模块住这儿'];

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/contract/unit-board.ts

@@ -0,0 +1,23 @@
+import type { ModuleBlocker } from './blocker.js';
+
+/**
+ * 卡片闸的两种档：capability 按环境读数判，none 无条件放行。
+ */
+export type GateMode =
+  | 'capability'
+  | 'none';
+
+/**
+ * 一次放行判定的结果；gated 为假时卡片不画。
+ */
+export interface UnitGate {
+  readonly gated: boolean;
+}
+
+/**
+ * 一个单元攒下的卡住态：blocker 顶掉卡片，notice 只提示；组装方产出，卡片消费。
+ */
+export interface UnitBlockers {
+  readonly blocker?: ModuleBlocker;
+  readonly notice?: ModuleBlocker;
+}