@dsh-workbench/shared 1.1.4 → 1.1.5

package/src/api/host-write.ts

@@ -1,3 +1,5 @@
+import type { InstallFailure } from '../contract/command.js';
+
 /**
  * 宿主写口的五条通道（偏好、动作、供给、工坊调试、工坊录制），是写路由的第一段。
  */
@@ -9,7 +11,8 @@ export type WriteChannel =
   | 'diy-record';
 
 /**
- * 写通道统一的结果：成了带值，没成带一句能给人看的话（可选明细与帮助链接）。
+ * 写通道统一的结果：成了带值，没成带一句能给人看的话（可选明细与帮助链接）；
+ * 安装类的失败多带一份结构化现场，界面据此给修法。
  */
 export type WriteOutcome<T> =
   | { readonly ok: true; readonly value: T }
@@ -18,4 +21,5 @@ export type WriteOutcome<T> =
       readonly message: string;
       readonly detail?: string;
       readonly helpUrl?: string;
+      readonly failure?: InstallFailure;
     };

package/src/api/workbench-client.ts

@@ -1,4 +1,5 @@
 import { API_PREFIX } from '../config/constants.js';
+import type { InstallFailure } from '../contract/command.js';
 
 /**
  * 宿主读口 / 写口回的错误：code 给判据分档，message 给人看，helpUrl 有就去点。
@@ -9,6 +10,7 @@ export interface ApiError {
   readonly detail?: string;
   readonly hint?: string;
   readonly helpUrl?: string;
+  readonly failure?: InstallFailure;
 }
 
 /**

package/src/components/ApprovalPlan.css

@@ -10,22 +10,21 @@
   color: var(--dsw-alias-label-secondary);
 }
 .wb-approvalRows {
-  display: flex;
-  flex-direction: column;
-  gap: var(--wb-len-2);
+  display: grid;
+  grid-template-columns: minmax(var(--wb-len-56), auto) minmax(0, 1fr);
+  column-gap: var(--wb-len-8);
+  row-gap: var(--wb-len-2);
+  align-items: baseline;
   margin: 0;
 }
 .wb-approvalRow {
-  display: flex;
-  align-items: baseline;
-  gap: var(--wb-len-8);
+  display: contents;
 }
 .wb-approvalLabel {
-  flex: none;
-  width: var(--wb-len-56);
   font-size: var(--dsw-font-xxs-12-font-size);
   line-height: var(--wb-line-18);
   color: var(--dsw-alias-label-tertiary);
+  overflow-wrap: anywhere;
 }
 .wb-approvalValue {
   margin: 0;

package/src/config/constants.ts

@@ -109,6 +109,12 @@ export const STORAGE_KEY_RIGHTBAR_COLUMN = "dsh-workbench.rightbar.column";
 /** 记住右栏宽度（像素数字的字符串）的 localStorage 键。 */
 export const STORAGE_KEY_RIGHTBAR_WIDTH = "dsh-workbench.rightbar.width";
 
+/** 记住「添加模块」浮层选过的安装源的 localStorage 键。 */
+export const STORAGE_KEY_MARKET_REGISTRY = "dsh-workbench.market.registry";
+
+/** 记住「添加模块」浮层上次填过的自定义源地址的 localStorage 键。 */
+export const STORAGE_KEY_MARKET_REGISTRY_CUSTOM = "dsh-workbench.market.registry.custom";
+
 /** 右栏宽度达到或超过多少像素就按全屏对待（阈值，像素）。 */
 export const RIGHTBAR_FULLSCREEN_WIDTH = 768;
 

package/src/contract/__tests__/needs.test.ts

@@ -37,6 +37,59 @@ describe('needs 校验矩阵', () => {
     );
   });
 
+  it('bin 声明 install → 过；install 写歪了要判红并点名', () => {
+    expect(
+      errorsOf({
+        kind: 'bin',
+        name: 'gitops',
+        purpose: '平台命令',
+        install: { kind: 'command', line: 'brew install pagoda/tap/gitops', platforms: ['darwin'] },
+        docs: 'https://internal/gitops',
+      }),
+    ).toEqual([]);
+
+    expect(errorsOf({ kind: 'bin', name: 'x', purpose: 'p', install: { kind: 'brew', line: 'x' } }).join(' ')).toContain(
+      'install.kind 只认 command',
+    );
+    expect(errorsOf({ kind: 'bin', name: 'x', purpose: 'p', install: { kind: 'command', line: '' } }).join(' ')).toContain(
+      'install.line 没写',
+    );
+    expect(
+      errorsOf({ kind: 'bin', name: 'x', purpose: 'p', install: { kind: 'command', line: 'x', platforms: ['mac'] } }).join(' '),
+    ).toContain('darwin / linux / win32');
+    expect(errorsOf({ kind: 'bin', name: 'x', purpose: 'p', install: { kind: 'command', line: 'x', url: 'y' } }).join(' ')).toContain(
+      'install 有不认识的字段 url',
+    );
+  });
+
+  it('bin 的 install 也可以是一个 npm 包（命令由包提供，装进隔离运行时）', () => {
+    expect(
+      errorsOf({
+        kind: 'bin',
+        name: 'gitops',
+        purpose: '平台命令',
+        install: {
+          kind: 'npm',
+          package: 'opencli-workflow',
+          registryEnv: 'ACME_REGISTRY',
+          registryDefault: 'https://registry.test/',
+        },
+      }),
+    ).toEqual([]);
+
+    expect(errorsOf({ kind: 'bin', name: 'x', purpose: 'p', install: { kind: 'npm' } }).join(' ')).toContain(
+      'install.package 没写',
+    );
+    expect(
+      errorsOf({
+        kind: 'bin',
+        name: 'x',
+        purpose: 'p',
+        install: { kind: 'npm', package: 'x', registryDefault: 'ftp://x' },
+      }).join(' '),
+    ).toContain('registryDefault 要是 http(s):// 或 file:// 的源地址');
+  });
+
   it('bin / env 写了 sources → 红（没有安装路径）', () => {
     expect(errorsOf({ kind: 'bin', name: 'x', purpose: '测试', sources: [npm] }).join(' ')).toContain(
       '不支持 sources',

package/src/contract/approval.ts

@@ -0,0 +1,4 @@
+/**
+ * agent 自己那句"这次想干什么"的参数名：插件命令族必填，审批屏把它画在详情座里，不进标题。
+ */
+export const APPROVAL_NOTE_ARG = 'approval_note';

package/src/contract/command.ts

@@ -23,3 +23,25 @@ export interface CommandResult {
 export interface CommandReader {
   run(request: CommandRequest): Promise<CommandResult>;
 }
+
+export const INSTALL_FAILURE_KINDS = ['permission', 'disk-full', 'sandbox', 'unknown'] as const;
+
+export type InstallFailureKind = (typeof INSTALL_FAILURE_KINDS)[number];
+
+export type InstallFix =
+  | { readonly kind: 'chown'; readonly path: string; readonly uid: number; readonly gid: number }
+  | { readonly kind: 'chmod'; readonly path: string }
+  | { readonly kind: 'space'; readonly path: string }
+  | { readonly kind: 'handoff' };
+
+export interface InstallFailure {
+  readonly kind: InstallFailureKind;
+  readonly command: string;
+  readonly exitCode: number | null;
+  readonly output: string;
+  readonly path?: string | undefined;
+  readonly mode?: string | undefined;
+  readonly owner?: { readonly uid: number; readonly gid: number } | undefined;
+  readonly current: { readonly uid: number; readonly gid: number };
+  readonly fix: InstallFix;
+}

package/src/contract/needs.ts

@@ -41,12 +41,31 @@ export interface NeedCommon {
   readonly id?: string;
 }
 
+/**
+ * 一条装这个可执行文件的命令；模块作者写，工作台照抄执行。
+ */
+export type BinInstall =
+  | {
+      readonly kind: 'command';
+      readonly line: string;
+      readonly platforms?: readonly string[] | undefined;
+    }
+  | {
+      readonly kind: 'npm';
+      readonly package: string;
+      readonly registryEnv?: string | undefined;
+      readonly registryDefault?: string | undefined;
+      readonly platforms?: readonly string[] | undefined;
+    };
+
 /**
  * 机器上要有一个可执行文件；探法是 `command -v` / `where`。
  */
 export interface BinNeed extends NeedCommon {
   readonly kind: 'bin';
   readonly name: string;
+  readonly install?: BinInstall | undefined;
+  readonly docs?: string | undefined;
 }
 
 /**
@@ -107,6 +126,8 @@ export const NEED_KEYS: readonly string[] = [
   'version',
   'sources',
   'secret',
+  'install',
+  'docs',
 ];
 
 /**
@@ -188,7 +209,7 @@ function sourcesProblemsOf(
   if (!Array.isArray(raw)) return [`${at}.sources 要是数组`];
   if (raw.length === 0) return [`${at}.sources 是空数组 —— 不代装就整条删掉`];
   if (allowed.length === 0) {
-    return [`${at} 这种需要不支持 sources —— 它没有「从哪装」这回事`];
+    return [`${at} 这种需要不支持 sources —— 要代装就写 install（一条命令）`];
   }
   const errors: string[] = [];
   raw.forEach((source, index) => {
@@ -214,6 +235,38 @@ function commonProblemsOf(raw: Readonly<Record<string, unknown>>, at: string): r
   return errors;
 }
 
+export function binInstallProblemsOf(raw: unknown, at: string): readonly string[] {
+  if (raw === undefined) return [];
+  if (!isRecord(raw)) return [`${at}.install 要是对象`];
+  const errors: string[] = [];
+  for (const key of Object.keys(raw)) {
+    if (!['kind', 'line', 'platforms', 'package', 'registryEnv', 'registryDefault'].includes(key)) {
+      errors.push(`${at}.install 有不认识的字段 ${key}`);
+    }
+  }
+  const kind = text(raw['kind']);
+  if (kind !== 'command' && kind !== 'npm') {
+    errors.push(`${at}.install.kind 只认 command（一条命令）或 npm（一个包，装进隔离运行时）`);
+  }
+  if (kind === 'command' && text(raw['line']) === '') {
+    errors.push(`${at}.install.line 没写 —— 要一条能直接粘进终端的命令`);
+  }
+  if (kind === 'npm' && text(raw['package']) === '') {
+    errors.push(`${at}.install.package 没写 —— 这个命令由哪个 npm 包提供`);
+  }
+  if (raw['registryDefault'] !== undefined && !REGISTRY_PATTERN.test(text(raw['registryDefault']))) {
+    errors.push(`${at}.install.registryDefault 要是 http(s):// 或 file:// 的源地址`);
+  }
+  if (raw['platforms'] !== undefined) {
+    if (!Array.isArray(raw['platforms']) || raw['platforms'].length === 0) {
+      errors.push(`${at}.install.platforms 要是非空数组`);
+    } else if (raw['platforms'].some((one) => !['darwin', 'linux', 'win32'].includes(text(one)))) {
+      errors.push(`${at}.install.platforms 只认 darwin / linux / win32`);
+    }
+  }
+  return errors;
+}
+
 function perKindProblemsOf(
   kind: NeedKind,
   raw: Readonly<Record<string, unknown>>,
@@ -223,6 +276,8 @@ function perKindProblemsOf(
   if (kind === 'bin' || kind === 'lib' || kind === 'env') {
     if (text(raw['name']) === '') errors.push(`${at}.name 没写`);
   }
+  if (kind === 'bin') errors.push(...binInstallProblemsOf(raw['install'], at));
+  if (raw['docs'] !== undefined && text(raw['docs']) === '') errors.push(`${at}.docs 是空串`);
   if (kind === 'extension') {
     if (text(raw['runtime']) === '') errors.push(`${at}.runtime 没写 —— 扩展属于哪个运行时（如 opencli）`);
     if (text(raw['name']) === '') errors.push(`${at}.name 没写`);

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

@@ -179,6 +179,8 @@ export interface BundleCancellationPayload {
 
 export type ModuleUpdateBlock = 'needs-workbench' | 'incompatible';
 
+export type LatestUnavailable = 'local' | 'no-registry' | 'not-registry' | 'probe-failed';
+
 export interface ModuleVersion {
   readonly unit: string;
   readonly pkg: string;
@@ -186,6 +188,7 @@ export interface ModuleVersion {
   readonly title?: UnitTitle;
   readonly latest?: string;
   readonly latestBlocked?: ModuleUpdateBlock;
+  readonly latestUnavailable?: LatestUnavailable;
   readonly local?: boolean;
   readonly refused?: readonly string[];
   readonly market?: MarketInstalledModule;

package/src/contract/unit.ts

@@ -24,12 +24,23 @@ export interface UnitCard {
   readonly order: number;
 }
 
+/**
+ * 合成工具背后那条 opencli 命令：插件名与命令名都是 opencli 那边的原名，`args` 是命令自己声明的参数名（按声明顺序）。
+ */
+export interface UnitToolOpencli {
+  readonly plugin: string;
+  readonly command: string;
+  readonly args: readonly string[];
+}
+
 /**
  * 一条工具在清单里的样子：全名加会不会写；审批按 writes 认领。
+ * `opencli` 只有「按已装插件合成」的单元写，手写模块的工具没有这一格。
  */
 export interface UnitTool {
   readonly name: string;
   readonly writes: boolean;
+  readonly opencli?: UnitToolOpencli;
 }
 
 /**

package/src/host/adapter-types.ts

@@ -25,6 +25,7 @@ export interface ProfileModule {
   readonly version: string;
   readonly registry?: string;
   readonly local?: boolean;
+  readonly fromRegistry?: boolean;
 }
 
 export interface ProfilePackage {
@@ -51,6 +52,7 @@ export interface RegistryEntry {
 export interface RegistryNotebook {
   sources(): readonly RegistryEntry[];
   remember(entries: readonly RegistryEntry[]): readonly string[];
+  swapScope?(scope: string, registry: string): () => void;
 }
 
 export interface SelfUpdatePaths {

package/src/host/data-error.ts

@@ -4,11 +4,12 @@ export class WorkbenchDataError extends Error {
   readonly hint?: string;
   readonly project?: unknown;
   readonly helpUrl?: string;
+  readonly failure?: unknown;
 
   constructor(
     code: string,
     message: string,
-    extra: { detail?: string; hint?: string; project?: unknown; helpUrl?: string } = {},
+    extra: { detail?: string; hint?: string; project?: unknown; helpUrl?: string; failure?: unknown } = {},
   ) {
     super(message);
     this.name = 'WorkbenchDataError';
@@ -17,5 +18,6 @@ export class WorkbenchDataError extends Error {
     if (extra.hint !== undefined) this.hint = extra.hint;
     if (extra.project !== undefined) this.project = extra.project;
     if (extra.helpUrl !== undefined) this.helpUrl = extra.helpUrl;
+    if (extra.failure !== undefined) this.failure = extra.failure;
   }
 }

package/src/host/http.ts

@@ -49,6 +49,7 @@ function toErrorPayload(error: unknown): Record<string, unknown> {
       ...(data.hint === undefined ? {} : { hint: data.hint }),
       ...(data.helpUrl === undefined ? {} : { helpUrl: data.helpUrl }),
       ...(data.project === undefined ? {} : { project: data.project }),
+      ...(data.failure === undefined ? {} : { failure: data.failure }),
     };
   }
   return { code: 'internal', message: error instanceof Error ? error.message : String(error) };

package/src/host/install-failure.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest';
+import {
+  classifyInstallFailure,
+  installFailureOf,
+  installTargets,
+  installWriteProblem,
+} from './install-failure.js';
+
+const CURRENT = { uid: 502, gid: 20 };
+
+describe('installTargets（从我们自己的安装命令里挑出写点）', () => {
+  it('挑出 --prefix 与原样带空格的路径', () => {
+    expect(installTargets(`npm i --prefix '/Users/a b/x' foo@1 --cache /tmp/c`)).toEqual([
+      '/Users/a b/x',
+      '/tmp/c',
+    ]);
+  });
+
+  it('没有 --prefix / --cache 就没有写点', () => {
+    expect(installTargets('npm ls --json --depth 0')).toEqual([]);
+  });
+});
+
+describe('classifyInstallFailure', () => {
+  it('EPERM / EACCES 都算权限', () => {
+    expect(classifyInstallFailure('npm error code EACCES')).toBe('permission');
+    expect(classifyInstallFailure('npm error syscall open errno EPERM')).toBe('permission');
+  });
+
+  it('ENOSPC 是盘满', () => {
+    expect(classifyInstallFailure('ENOSPC: no space left on device')).toBe('disk-full');
+  });
+
+  it('认不出来就说认不出来', () => {
+    expect(classifyInstallFailure('')).toBe('unknown');
+  });
+});
+
+describe('installFailureOf（从现场推到修法）', () => {
+  it('属主不是当前账号 → chown 回自己', () => {
+    const failure = installFailureOf({
+      command: 'npm i --prefix /x foo@1',
+      exitCode: 1,
+      output: 'EACCES: permission denied',
+      path: '/x',
+      owner: { uid: 0, gid: 0 },
+      mode: '755',
+      writable: false,
+      current: CURRENT,
+    });
+
+    expect(failure.kind).toBe('permission');
+    expect(failure.fix).toEqual({ kind: 'chown', path: '/x', uid: 502, gid: 20 });
+  });
+
+  it('属主是自己、只是没写位 → chmod，不给 sudo', () => {
+    const failure = installFailureOf({
+      command: 'npm i --prefix /x foo@1',
+      exitCode: 1,
+      output: 'EACCES: permission denied',
+      path: '/x',
+      owner: { uid: 502, gid: 20 },
+      mode: '555',
+      writable: false,
+      current: CURRENT,
+    });
+
+    expect(failure.fix).toEqual({ kind: 'chmod', path: '/x' });
+  });
+
+  it('属主是自己、明明可写却报 EPERM → 是被别的沙箱拦的，不给一条没用的 sudo', () => {
+    const failure = installFailureOf({
+      command: 'npm i --prefix /x foo@1',
+      exitCode: 1,
+      output: 'EPERM: operation not permitted',
+      path: '/x',
+      owner: { uid: 502, gid: 20 },
+      mode: '755',
+      writable: true,
+      current: CURRENT,
+    });
+
+    expect(failure.kind).toBe('sandbox');
+    expect(failure.fix).toEqual({ kind: 'handoff' });
+  });
+
+  it('盘满 → 指向精简的命令，而不是 chown', () => {
+    const failure = installFailureOf({
+      command: 'npm i --prefix /x foo@1',
+      exitCode: 1,
+      output: 'ENOSPC: no space left on device',
+      path: '/x',
+      current: CURRENT,
+    });
+
+    expect(failure.kind).toBe('disk-full');
+    expect(failure.fix).toEqual({ kind: 'space', path: '/x' });
+  });
+
+  it('认不出来 → 交接给 agent，不硬猜修法', () => {
+    const failure = installFailureOf({
+      command: 'npm i --prefix /x foo@1',
+      exitCode: 255,
+      output: 'something odd',
+      current: CURRENT,
+    });
+
+    expect(failure.kind).toBe('unknown');
+    expect(failure.fix).toEqual({ kind: 'handoff' });
+  });
+});
+
+describe('installWriteProblem（装之前先看一眼，省得白跑）', () => {
+  it('只盯安装动词：npm ls 这种读命令不拦', () => {
+    expect(installWriteProblem({ command: 'npm ls --prefix /x foo --json' })).toBeUndefined();
+  });
+
+  it('目录不存在 → 退到最近的祖先，不报假问题', () => {
+    expect(installWriteProblem({ command: `npm i --prefix ${process.cwd()}/definitely-missing-dir foo` })).toBeUndefined();
+  });
+});

package/src/host/install-failure.ts

@@ -0,0 +1,198 @@
+import { accessSync, constants, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type { InstallFailure, InstallFailureKind } from '../contract/command.js';
+
+const TARGET_FLAGS = ['--prefix', '--cache', '--dir', '--store-dir'];
+
+const INSTALL_VERBS = /^\s*npm\s+(i|install|add)\b/;
+
+const NPM_PATH = /^npm (?:error|ERR!) path (.+)$/m;
+
+export interface DirFacts {
+  readonly mode: string;
+  readonly owner: { readonly uid: number; readonly gid: number };
+  readonly writable: boolean;
+}
+
+export function commandTokens(command: string): string[] {
+  const tokens: string[] = [];
+  const token = /'([^']*)'|"([^"]*)"|(\S+)/g;
+  for (let match = token.exec(command); match !== null; match = token.exec(command)) {
+    tokens.push(match[1] ?? match[2] ?? match[3] ?? '');
+  }
+  return tokens;
+}
+
+export function installTargets(command: string): string[] {
+  const tokens = commandTokens(command);
+  const targets: string[] = [];
+  for (let index = 0; index < tokens.length - 1; index += 1) {
+    if (TARGET_FLAGS.includes(tokens[index] ?? '')) targets.push(tokens[index + 1] ?? '');
+  }
+  return targets.filter((target) => target !== '');
+}
+
+export function failurePathIn(output: string): string | undefined {
+  const path = NPM_PATH.exec(output)?.[1]?.trim();
+  return path === undefined || path === '' ? undefined : path;
+}
+
+export function nearestDir(path: string): string | undefined {
+  let at = path;
+  for (;;) {
+    const here = (): boolean => {
+      try {
+        return statSync(at).isDirectory();
+      } catch {
+        return false;
+      }
+    };
+    if (here()) return at;
+    const up = dirname(at);
+    if (up === at) return undefined;
+    at = up;
+  }
+}
+
+export type WriteState = 'ok' | 'denied' | 'unknown';
+
+export function writeStateOf(dir: string): WriteState {
+  try {
+    accessSync(dir, constants.W_OK);
+    return 'ok';
+  } catch (error) {
+    return (error as { code?: string }).code === 'EACCES' ? 'denied' : 'unknown';
+  }
+}
+
+export function dirFacts(dir: string): DirFacts | undefined {
+  try {
+    const stats = statSync(dir);
+    return {
+      mode: (stats.mode & 0o777).toString(8),
+      owner: { uid: stats.uid, gid: stats.gid },
+      writable: writeStateOf(dir) === 'ok',
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+export function currentUser(): { readonly uid: number; readonly gid: number } {
+  return { uid: process.getuid?.() ?? -1, gid: process.getgid?.() ?? -1 };
+}
+
+export function classifyInstallFailure(output: string): InstallFailureKind {
+  const text = output.toLowerCase();
+  if (/enospc|no space left/.test(text)) return 'disk-full';
+  if (/eacces|eperm|permission denied|operation not permitted|access is denied/.test(text)) return 'permission';
+  return 'unknown';
+}
+
+export interface InstallFailureFacts {
+  readonly command: string;
+  readonly exitCode: number | null;
+  readonly output: string;
+  readonly kind?: InstallFailureKind | undefined;
+  readonly path?: string | undefined;
+  readonly mode?: string | undefined;
+  readonly owner?: { readonly uid: number; readonly gid: number } | undefined;
+  readonly writable?: boolean | undefined;
+  readonly current: { readonly uid: number; readonly gid: number };
+}
+
+export function installFailureOf(facts: InstallFailureFacts): InstallFailure {
+  const kind = facts.kind ?? classifyInstallFailure(facts.output);
+  const path = facts.path;
+  const base = {
+    command: facts.command,
+    exitCode: facts.exitCode,
+    output: facts.output,
+    ...(path === undefined ? {} : { path }),
+    ...(facts.mode === undefined ? {} : { mode: facts.mode }),
+    ...(facts.owner === undefined ? {} : { owner: facts.owner }),
+    current: facts.current,
+  };
+  if (kind === 'disk-full') {
+    return { ...base, kind, fix: path === undefined ? { kind: 'handoff' } : { kind: 'space', path } };
+  }
+  if (kind === 'permission' && path !== undefined) {
+    const owner = facts.owner;
+    if (owner !== undefined && owner.uid !== facts.current.uid && facts.current.uid >= 0) {
+      return { ...base, kind, fix: { kind: 'chown', path, uid: facts.current.uid, gid: facts.current.gid } };
+    }
+    if (facts.writable === false) {
+      return { ...base, kind, fix: { kind: 'chmod', path } };
+    }
+    if (facts.writable === true) {
+      return { ...base, kind: 'sandbox', fix: { kind: 'handoff' } };
+    }
+  }
+  return { ...base, kind, fix: { kind: 'handoff' } };
+}
+
+export function diagnoseInstallFailure(input: {
+  readonly command: string;
+  readonly exitCode: number | null;
+  readonly output: string;
+  readonly fallback?: string | undefined;
+}): InstallFailure {
+  const current = currentUser();
+  const candidates = [
+    failurePathIn(input.output),
+    ...installTargets(input.command),
+    input.fallback,
+  ].filter((path): path is string => path !== undefined && path !== '');
+  for (const candidate of candidates) {
+    const dir = nearestDir(candidate);
+    if (dir === undefined) continue;
+    const facts = dirFacts(dir);
+    if (facts === undefined) continue;
+    return installFailureOf({
+      command: input.command,
+      exitCode: input.exitCode,
+      output: input.output,
+      path: dir,
+      mode: facts.mode,
+      owner: facts.owner,
+      writable: facts.writable,
+      current,
+    });
+  }
+  return installFailureOf({
+    command: input.command,
+    exitCode: input.exitCode,
+    output: input.output,
+    current,
+  });
+}
+
+export function installWriteProblem(input: {
+  readonly command: string;
+  readonly fallback?: string | undefined;
+}): InstallFailure | undefined {
+  if (!INSTALL_VERBS.test(input.command)) return undefined;
+  const current = currentUser();
+  const candidates = [...installTargets(input.command), input.fallback].filter(
+    (path): path is string => path !== undefined && path !== '',
+  );
+  for (const candidate of candidates) {
+    const dir = nearestDir(candidate);
+    if (dir === undefined) continue;
+    if (writeStateOf(dir) !== 'denied') continue;
+    const facts = dirFacts(dir);
+    if (facts === undefined) continue;
+    return installFailureOf({
+      command: input.command,
+      exitCode: null,
+      output: '',
+      kind: 'permission',
+      path: dir,
+      mode: facts.mode,
+      owner: facts.owner,
+      writable: facts.writable,
+      current,
+    });
+  }
+  return undefined;
+}