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

package/src/host/plugin-source.ts

@@ -1,11 +1,9 @@
-import type { PluginSource } from '../api/unit.js';
+import type { SupplySource } from '../contract/needs.js';
+import type { ProvisionProblem } from '../contract/plugin-source.js';
 import { quoteShellArg } from './shell-text.js';
-import { npmCacheDir, toolchainOpencliDir, vendorPeerLink, vendorPrefix } from '../host/opencli-runtime.js';
+import { npmCacheDir, toolchainOpencliDir, vendorPeerLink, vendorPrefix } from './paths.js';
 
-export type PluginSourceProblem =
-  | "not-declared"
-  | "env-missing"
-  | "malformed";
+export type { ProvisionProblem } from '../contract/plugin-source.js';
 
 export interface PluginSourceCommand {
   readonly line: string;
@@ -20,7 +18,7 @@ export type ResolvedPluginSource =
     }
   | {
       readonly ok: false;
-      readonly problem: PluginSourceProblem;
+      readonly problem: ProvisionProblem;
       readonly env?: string;
     };
 
@@ -28,15 +26,11 @@ export interface PluginSourceOptions {
   readonly command?: string;
   readonly plugin?: string;
   readonly version?: string;
-  readonly mode?: "install" | "update";
+  readonly mode?: 'install' | 'update';
 }
 
 function mergeLines(commands: readonly PluginSourceCommand[]): string {
-  return commands
-    .map((item) =>
-      item.optional === true ? `(${item.line} || true)` : item.line,
-    )
-    .join(" && ");
+  return commands.map((item) => (item.optional === true ? `(${item.line} || true)` : item.line)).join(' && ');
 }
 
 function envValue(
@@ -44,21 +38,21 @@ function envValue(
   name: string,
 ): { readonly ok: true; readonly value: string } | { readonly ok: false } {
   const value = env[name]?.trim();
-  return value === undefined || value === ""
-    ? { ok: false }
-    : { ok: true, value };
+  return value === undefined || value === '' ? { ok: false } : { ok: true, value };
 }
 
 export function npmRegistryOf(
-  source: { readonly registryEnv: string; readonly registryDefault?: string },
+  source: { readonly registryEnv?: string; readonly registryDefault?: string },
   env: Readonly<Record<string, string | undefined>>,
-): { readonly ok: true; readonly value: string } | { readonly ok: false } {
-  const fromEnv = envValue(env, source.registryEnv);
-  if (fromEnv.ok) return fromEnv;
+): { readonly ok: true; readonly value: string } | { readonly ok: false; readonly env: string } {
+  const name = source.registryEnv ?? '';
+  if (name !== '') {
+    const fromEnv = envValue(env, name);
+    if (fromEnv.ok) return fromEnv;
+  }
   const fallback = source.registryDefault?.trim();
-  return fallback === undefined || fallback === ""
-    ? { ok: false }
-    : { ok: true, value: fallback };
+  if (fallback === undefined || fallback === '') return { ok: false, env: name };
+  return { ok: true, value: fallback };
 }
 
 function installOne(command: string, spec: string): ResolvedPluginSource {
@@ -66,28 +60,28 @@ function installOne(command: string, spec: string): ResolvedPluginSource {
   return { ok: true, commands: [{ line }], line };
 }
 
+function pluginPackageOf(source: SupplySource, plugin: string): string {
+  if (source.kind === 'npm') {
+    const pkg = source.package?.trim() ?? '';
+    if (pkg !== '') return pkg;
+    return plugin.trim() === '' ? '' : `opencli-plugin-${plugin.trim()}`;
+  }
+  if (source.kind === 'git') return source.url.trim();
+  return '';
+}
+
 function npmSource(
-  source: {
-    readonly package: string;
-    readonly registryEnv: string;
-    readonly registryDefault?: string;
-  },
+  source: SupplySource & { kind: 'npm' },
   env: Readonly<Record<string, string | undefined>>,
   options: PluginSourceOptions,
 ): ResolvedPluginSource {
   const registry = npmRegistryOf(source, env);
-  if (!registry.ok)
-    return { ok: false, problem: "env-missing", env: source.registryEnv };
-
-  const name = source.package.trim();
-  if (name === "") return { ok: false, problem: "malformed" };
-
-  const {
-    command = "opencli",
-    plugin = "",
-    version = "latest",
-    mode = "install",
-  } = options;
+  if (!registry.ok) return { ok: false, problem: 'env-missing', env: registry.env };
+
+  const { command = 'opencli', plugin = '', version = 'latest', mode = 'install' } = options;
+  const name = pluginPackageOf(source, plugin);
+  if (name === '') return { ok: false, problem: 'malformed' };
+
   const prefix = vendorPrefix();
   const dirInPrefix = `${prefix}/node_modules/${name}`;
   const peer = vendorPeerLink();
@@ -95,20 +89,20 @@ function npmSource(
   const commands: PluginSourceCommand[] = [
     {
       line: [
-        "npm i",
+        'npm i',
         `--prefix ${quoteShellArg(prefix)}`,
         quoteShellArg(`${name}@${version}`),
         `--registry ${quoteShellArg(registry.value)}`,
         `--cache ${quoteShellArg(npmCacheDir())}`,
-      ].join(" "),
+      ].join(' '),
     },
     {
       line: `rm -rf ${quoteShellArg(peer.dir)} && mkdir -p ${quoteShellArg(peer.parent)} && ln -s ${quoteShellArg(toolchainOpencliDir())} ${quoteShellArg(peer.dir)}`,
     },
   ];
 
-  if (mode === "install") {
-    if (plugin !== "") {
+  if (mode === 'install') {
+    if (plugin !== '') {
       commands.push({
         line: `${quoteShellArg(command)} plugin uninstall ${quoteShellArg(plugin)}`,
         optional: true,
@@ -123,23 +117,21 @@ function npmSource(
 }
 
 export function resolvePluginSource(
-  source: PluginSource | undefined,
+  source: SupplySource | undefined,
   env: Readonly<Record<string, string | undefined>>,
   options: PluginSourceOptions = {},
 ): ResolvedPluginSource {
-  if (source === undefined) return { ok: false, problem: "not-declared" };
+  if (source === undefined) return { ok: false, problem: 'not-declared' };
 
-  const command = options.command ?? "opencli";
-  if (source.kind === "git") {
+  const command = options.command ?? 'opencli';
+  if (source.kind === 'git') {
     const url = source.url.trim();
-    return url === ""
-      ? { ok: false, problem: "malformed" }
-      : installOne(command, url);
+    return url === '' ? { ok: false, problem: 'malformed' } : installOne(command, url);
   }
-  if (source.kind === "npm") return npmSource(source, env, options);
+  if (source.kind === 'npm') return npmSource(source, env, options);
 
-  const value = envValue(env, source.env);
-  return value.ok
-    ? installOne(command, value.value)
-    : { ok: false, problem: "env-missing", env: source.env };
+  const value = source.env === undefined ? { ok: false as const } : envValue(env, source.env);
+  if (value.ok) return installOne(command, value.value);
+  if (source.path !== undefined && source.path.trim() !== '') return installOne(command, source.path.trim());
+  return { ok: false, problem: 'env-missing', env: source.env ?? '' };
 }

package/src/host/plugin.ts

@@ -0,0 +1,39 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const OPENCLI_MANIFEST_FILE = 'opencli-plugin.json';
+
+function asRecord(value: unknown): Readonly<Record<string, unknown>> | undefined {
+  return typeof value === 'object' && value !== null ? (value as Readonly<Record<string, unknown>>) : undefined;
+}
+
+function isCommandFile(name: string): boolean {
+  if (name.endsWith('.d.ts') || name.endsWith('.test.ts')) return false;
+  if (name.endsWith('.d.js')) return false;
+  return name.endsWith('.ts') || name.endsWith('.js');
+}
+
+function pluginManifestOf(dir: string): Readonly<Record<string, unknown>> | undefined {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(join(dir, OPENCLI_MANIFEST_FILE), 'utf8'));
+    if (Array.isArray(parsed)) return undefined;
+    return asRecord(parsed);
+  } catch {
+    return undefined;
+  }
+}
+
+function hasCommandFile(dir: string): boolean {
+  try {
+    return readdirSync(dir).some(isCommandFile);
+  } catch {
+    return false;
+  }
+}
+
+export function pluginAt(dir: string): { readonly name?: string } | undefined {
+  const manifest = pluginManifestOf(dir);
+  if (manifest === undefined || !hasCommandFile(dir)) return undefined;
+  const name = manifest.name;
+  return typeof name === 'string' && name.trim() !== '' ? { name: name.trim() } : {};
+}

package/src/host/port-types.ts

@@ -0,0 +1,222 @@
+import type { DshHostContext, DshShell } from '../api/dsh.js';
+import type { LibNeed, SupplySource } from '../contract/needs.js';
+import type { NeedProbeInput, UnitCapability } from '../contract/unit-capability.js';
+import type { WorkbenchSelfUpdate } from '../contract/protocol/bundle-install.js';
+import type {
+  BundleManager,
+  InstalledModule,
+  OpencliResolution,
+  ProfileModule,
+  ProfilePackage,
+  RegistryNotebook,
+  SelfUpdateRequest,
+  SelfUpdateStart,
+} from './adapter-types.js';
+import type { PostResource, RouteHandler, RouteTable } from './http.js';
+import type { PluginSourceOptions, ResolvedPluginSource } from './plugin-source.js';
+
+export interface LoggerLike {
+  info?(message: string): void;
+  warn?(message: string): void;
+}
+
+export interface ProfilePort {
+  dirOf(ctx: DshHostContext): string | null;
+  dshPlugins(ctx: DshHostContext): RouteHandler;
+  selfUpdateView(root: string, profile: string): WorkbenchSelfUpdate | undefined;
+}
+
+export type SupplyPluginSource = ResolvedPluginSource;
+
+export interface SupplyPackageRoute {
+  readonly kind: 'opencli-plugin' | 'dsh-bundle' | 'neither';
+  readonly pkg?: string;
+  readonly pluginName?: string;
+}
+
+export interface SupplyRelease {
+  readonly installed?: string;
+  readonly latest?: string;
+  readonly missing?: readonly string[];
+}
+
+export interface SupplyNpmRef {
+  readonly name: string;
+  readonly version?: string;
+}
+
+export interface SupplyPluginInstallOptions {
+  readonly spec: string;
+  readonly command: string;
+  readonly registry?: string | undefined;
+  readonly pluginName?: string | undefined;
+}
+
+export interface SupplyLatestOptions {
+  readonly shell: DshShell;
+  readonly name: string;
+  readonly registry: string;
+  readonly force?: boolean;
+}
+
+export interface SupplyMissingPartsOptions {
+  readonly shell: DshShell;
+  readonly registry: string;
+  readonly version: string;
+  readonly force?: boolean;
+}
+
+export interface SupplyProbeReleaseOptions {
+  readonly shell: DshShell;
+  readonly package: string;
+  readonly registry?: string | undefined;
+  readonly force?: boolean;
+}
+
+export interface EnvSupplyPort {
+  resolvePluginSource(
+    source: SupplySource | undefined,
+    env: Readonly<Record<string, string | undefined>>,
+    options?: PluginSourceOptions,
+  ): ResolvedPluginSource;
+  libInstallCommand(options: {
+    readonly need: LibNeed;
+    readonly source: Extract<SupplySource, { kind: 'npm' }>;
+    readonly version?: string | undefined;
+  }): string;
+  pluginInstallPlan(options: SupplyPluginInstallOptions): ResolvedPluginSource;
+  latestVersion(options: SupplyLatestOptions): Promise<string | undefined>;
+  missingReleaseParts(options: SupplyMissingPartsOptions): Promise<readonly string[]>;
+  probeRelease(options: SupplyProbeReleaseOptions): Promise<SupplyRelease | undefined>;
+  splitNpmSpec(spec: string): SupplyNpmRef | undefined;
+}
+
+export interface ModulePort {
+  isolatedHome(): string;
+  cliCatalogPath(): string;
+  vendorPluginsDir(): string;
+  opencliInstallCommand(): string;
+  profileDirOf(ctx: DshHostContext): string | null;
+  profileModules(dir: string | null): readonly ProfileModule[];
+  readInstalledModule(dir: string | null, pkg: string): InstalledModule;
+  readProfilePackage(dir: string | null, pkg: string): ProfilePackage | undefined;
+  readBundleManager(ctx: DshHostContext): BundleManager | undefined;
+  createRegistryNotebook(dir: string | null): RegistryNotebook;
+  declarationGaps(dir: string | null): readonly { readonly pkg: string }[] | undefined;
+  moduleDeclarationOf(dir: string | null, pkg: string): unknown;
+  registryDeclarationOf(options: {
+    readonly shell: DshShell;
+    readonly name: string;
+    readonly registry: string;
+    readonly force?: boolean;
+  }): Promise<unknown>;
+  pathDeclarationOf(spec: string): unknown;
+  declarationRefusalOf(name: string, raw: unknown): readonly string[];
+  refusalReason(): string;
+  packageRouteOf(options: {
+    readonly spec: string;
+    readonly shell?: DshShell | undefined;
+    readonly registry?: string | undefined;
+    readonly force?: boolean;
+  }): Promise<SupplyPackageRoute | undefined>;
+  isNewerVersion(left: string, right: string): boolean;
+  startSelfUpdate(request: SelfUpdateRequest, onError: (message: string) => void): SelfUpdateStart;
+}
+
+export interface SupplyPort extends EnvSupplyPort, ModulePort {
+  readonly env: EnvSupplyPort;
+  readonly modules: ModulePort;
+}
+
+export interface ProbeUnitsOptions {
+  readonly shell: DshShell;
+  readonly runtimeCommands: Readonly<Record<string, string>>;
+  readonly units: readonly NeedProbeInput[];
+  readonly force?: boolean;
+}
+
+export interface ProbePreflightInput {
+  readonly routes: RouteTable;
+  readonly ctx: DshHostContext;
+  readonly shell: DshShell;
+  readonly opencliCommand: string;
+  readonly installCommand?: string | undefined;
+  readonly warmReads: () => readonly (readonly string[])[];
+}
+
+export interface ProbePort {
+  probeUnits(options: ProbeUnitsOptions): Promise<UnitCapability[]>;
+  registerPreflight(input: ProbePreflightInput): void;
+  declaredPluginCommands(profileDir: string | null): ReadonlyMap<string, ReadonlySet<string>>;
+}
+
+export interface RuntimeSeedOptions {
+  readonly corePackageUrl: string;
+  readonly log: (message: string) => void;
+}
+
+export interface RuntimePort {
+  packageRoot(moduleUrl: string): string;
+  opencliCommand(ctx: DshHostContext): OpencliResolution;
+  seed(ctx: DshHostContext, options: RuntimeSeedOptions): void;
+  warnUnwritableRoot(ctx: DshHostContext): void;
+}
+
+export interface PluginDeclarationSource {
+  readonly pkg: string;
+  readonly declaration: unknown;
+}
+
+export interface PluginRowRef {
+  readonly id: string;
+  readonly pkg: string;
+  readonly name?: string | undefined;
+}
+
+export interface PluginRowsSource {
+  listPlugins(workspace: string | null): readonly PluginRowRef[];
+  subscribe?(listener: () => void): () => void;
+}
+
+export interface PluginUnitsPort {
+  refresh(options?: { readonly force?: boolean }): Promise<unknown>;
+  touch(): void;
+  report(): unknown;
+  dispose(): void;
+}
+
+export interface PluginUnitsInput {
+  readonly registry: { registerPlugin(face: unknown): () => void };
+  readonly rows: () => readonly PluginRowRef[];
+  readonly declared: (plugin: string) => ReadonlySet<string>;
+  readonly toolNames?: () => ReadonlySet<string>;
+  readonly logger?: LoggerLike | undefined;
+}
+
+export interface PluginSurface {
+  declarationLookup(profileDir: string | null): (unit: string) => PluginDeclarationSource | undefined;
+  createUnits(input: PluginUnitsInput): PluginUnitsPort;
+}
+
+export interface ConfigSyncInput {
+  readonly home: string;
+  readonly self: string;
+  readonly profileDir: string | null;
+  readonly reconcile?: (() => Promise<boolean | void>) | undefined;
+}
+
+export interface ProfileCreateInput {
+  readonly home: string;
+  readonly self: string;
+  readonly packageRoot: string;
+  readonly runSetup?:
+    | ((env: Readonly<Record<string, string>>) => Promise<{ ok: boolean; log: string }>)
+    | undefined;
+}
+
+export interface HostActions {
+  configSyncHandler(input: ConfigSyncInput): RouteHandler;
+  profileCreateHandler(input: ProfileCreateInput): RouteHandler;
+  configSyncAction(input: ConfigSyncInput): PostResource;
+  profileCreateAction(input: ProfileCreateInput): PostResource;
+}

package/src/host/preflight.ts

@@ -0,0 +1,31 @@
+export type PreflightStepId = 'toolchain' | 'opencli' | 'bridge' | 'diy' | 'warm';
+export type PreflightStepStatus = 'pending' | 'running' | 'ok' | 'warn' | 'failed';
+export type PreflightFailure = 'permission' | 'network' | 'missing' | 'unknown';
+export type PreflightGuidance = 'install' | 'path' | 'shell';
+export type PreflightBridgeIssue = 'daemon' | 'extension' | 'profile' | 'stale' | 'unknown';
+
+export interface PreflightStep {
+  readonly id: PreflightStepId;
+  readonly status: PreflightStepStatus;
+  readonly detail?: string;
+  readonly action?: string;
+  readonly command?: string;
+}
+
+export interface PreflightDiyGap {
+  readonly rows: readonly string[];
+  readonly detail: string;
+  readonly command: string;
+}
+
+export interface PreflightSnapshot {
+  readonly phase: 'idle' | 'checking' | 'installing' | 'ready' | 'failed';
+  readonly steps: readonly PreflightStep[];
+  readonly at: number;
+  readonly error?: string;
+  readonly failure?: PreflightFailure;
+  readonly guidance?: PreflightGuidance;
+  readonly bridgeIssues?: readonly PreflightBridgeIssue[];
+  readonly diyGap?: PreflightDiyGap;
+  readonly canWakeBrowser?: boolean;
+}

package/src/host/profile-port.ts

@@ -0,0 +1,9 @@
+import type { DshHostContext } from '../api/dsh.js';
+import { adaptersOf } from './adapters.js';
+import type { ProfilePort } from './port-types.js';
+export type { ProfilePort } from './port-types.js';
+
+
+export function profilePortOf(ctx: DshHostContext): ProfilePort {
+  return adaptersOf(ctx).profile;
+}

package/src/host/provision.ts

@@ -1,4 +1,4 @@
-import type { ProvisionAction } from '../api/workbench-contract.js';
+import type { ProvisionAction } from '../contract/workbench-contract.js';
 
 export type { ProvisionAction };
 
@@ -7,6 +7,7 @@ export const PROVISION_ACTIONS = [
   'update',
   'uninstall',
   'install-bundle',
+  'install-version',
   'update-bundle',
   'remove-bundle',
   'cancel-install',
@@ -33,7 +34,7 @@ export type ProvisionTarget = 'unit' | 'id' | 'spec' | 'name' | 'requestId';
 
 export function provisionTargetOf(action: ProvisionAction): ProvisionTarget {
   if (action === 'update-dependency') return 'id';
-  if (action === 'install-bundle') return 'spec';
+  if (action === 'install-bundle' || action === 'install-version') return 'spec';
   if (action === 'remove-bundle') return 'name';
   if (action === 'update-plugin' || action === 'uninstall-plugin') return 'name';
   if (action === 'update-workbench') return 'name';
@@ -77,7 +78,7 @@ function stringsOf(value: unknown): string[] | undefined {
 
 function requestOf(action: ProvisionAction, value: string): ProvisionRequest {
   if (action === 'update-dependency') return { action, id: value };
-  if (action === 'install-bundle') return { action, spec: value };
+  if (action === 'install-bundle' || action === 'install-version') return { action, spec: value };
   if (action === 'remove-bundle') return { action, name: value };
   if (action === 'update-plugin' || action === 'uninstall-plugin') return { action, name: value };
   if (action === 'update-workbench') return { action, name: value };
@@ -111,7 +112,9 @@ export function parseProvisionBody(body: unknown): ProvisionParsed {
   if (typeof value !== 'string' || value.trim() === '') {
     return { ok: false, code: TARGET_CODE[target], message: `缺少 ${target}` };
   }
-  if (wanted !== 'install-bundle') return { ok: true, request: requestOf(wanted, value.trim()) };
+  if (wanted !== 'install-bundle' && wanted !== 'install-version') {
+    return { ok: true, request: requestOf(wanted, value.trim()) };
+  }
 
   const registry = typeof raw.registry === 'string' && raw.registry.trim() !== '' ? raw.registry.trim() : undefined;
   const approvedBuilds = stringsOf(raw.approvedBuilds);