@dsh-workbench/shared 1.1.4 → 1.1.6

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;
+}

package/src/host/installed-sources.test.ts

@@ -0,0 +1,80 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+  forgetPackageSource,
+  installedSourcesFile,
+  packageSourceOf,
+  readInstalledSources,
+  rememberPackageSource,
+} from './installed-sources.js';
+
+const dirs: string[] = [];
+
+function profile(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'wb-sources-'));
+  dirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+describe('按包记安装来源（检查更新只认这一份）', () => {
+  it('写一条再读回来：版本与源都在，文件是临时名换过去的', () => {
+    const dir = profile();
+    rememberPackageSource(dir, '@a/mod', { version: '0.3.1', registry: 'https://r1.example/' });
+
+    expect(packageSourceOf(dir, '@a/mod')).toEqual({ version: '0.3.1', registry: 'https://r1.example/' });
+    expect(fs.existsSync(`${installedSourcesFile(dir)}.tmp`)).toBe(false);
+  });
+
+  it('★ 同一个 scope 的两个包可以各记各的源（.npmrc 做不到这件事）', () => {
+    const dir = profile();
+    rememberPackageSource(dir, '@x/a', { version: '1.0.0', registry: 'https://r1.example/' });
+    rememberPackageSource(dir, '@x/b', { version: '2.0.0', registry: 'https://r2.example/' });
+
+    expect(packageSourceOf(dir, '@x/a')?.registry).toBe('https://r1.example/');
+    expect(packageSourceOf(dir, '@x/b')?.registry).toBe('https://r2.example/');
+    expect(readInstalledSources(dir)).toHaveProperty('@x/a');
+  });
+
+  it('再装一次同一个包 → 覆盖成这次记录的版本与源', () => {
+    const dir = profile();
+    rememberPackageSource(dir, '@x/a', { version: '1.0.0', registry: 'https://r1.example/' });
+    rememberPackageSource(dir, '@x/a', { version: '1.1.0', registry: 'https://r2.example/' });
+
+    expect(packageSourceOf(dir, '@x/a')).toEqual({ version: '1.1.0', registry: 'https://r2.example/' });
+  });
+
+  it('卸载后删掉；没有这条时也不写空文件', () => {
+    const dir = profile();
+    rememberPackageSource(dir, '@x/a', { version: '1.0.0', registry: 'https://r1.example/' });
+    forgetPackageSource(dir, '@x/a');
+
+    expect(packageSourceOf(dir, '@x/a')).toBeUndefined();
+    const before = fs.readFileSync(installedSourcesFile(dir), 'utf8');
+    forgetPackageSource(dir, '@x/never');
+    expect(fs.readFileSync(installedSourcesFile(dir), 'utf8')).toBe(before);
+  });
+
+  it('文件坏了 / 没有 / profile 不认识 → 一律当没有记录，不抛', () => {
+    const dir = profile();
+    fs.writeFileSync(installedSourcesFile(dir), '{ 坏的 json', 'utf8');
+    expect(readInstalledSources(dir)).toEqual({});
+    expect(packageSourceOf(dir, '@x/a')).toBeUndefined();
+    expect(readInstalledSources(null)).toEqual({});
+  });
+
+  it('空包名 / 空源 / 空版本不落盘（别把没问到的写进去当事实）', () => {
+    const dir = profile();
+    rememberPackageSource(dir, ' ', { version: '1.0.0', registry: 'https://r1.example/' });
+    rememberPackageSource(dir, '@x/a', { version: '', registry: 'https://r1.example/' });
+    rememberPackageSource(dir, '@x/b', { version: '1.0.0', registry: ' ' });
+
+    expect(readInstalledSources(dir)).toEqual({});
+    expect(fs.existsSync(installedSourcesFile(dir))).toBe(false);
+  });
+});

package/src/host/installed-sources.ts

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export interface InstalledSource {
+  readonly version: string;
+  readonly registry: string;
+}
+
+export type InstalledSourceMap = Readonly<Record<string, InstalledSource>>;
+
+const FILE_NAME = '.dsh-workbench-sources.json';
+const FILE_VERSION = 1;
+
+function asRecord(value: unknown): Readonly<Record<string, unknown>> | undefined {
+  return typeof value === 'object' && value !== null ? (value as Readonly<Record<string, unknown>>) : undefined;
+}
+
+function asText(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+export function installedSourcesFile(profileDir: string): string {
+  return path.join(profileDir, FILE_NAME);
+}
+
+export function readInstalledSources(profileDir: string | null): InstalledSourceMap {
+  if (profileDir === null) return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(fs.readFileSync(installedSourcesFile(profileDir), 'utf8'));
+  } catch {
+    return {};
+  }
+  const packages = asRecord(asRecord(parsed)?.packages);
+  if (packages === undefined) return {};
+  const found: Record<string, InstalledSource> = {};
+  for (const [pkg, value] of Object.entries(packages)) {
+    const record = asRecord(value);
+    if (record === undefined) continue;
+    const version = asText(record.version);
+    const registry = asText(record.registry);
+    if (pkg === '' || version === '' || registry === '') continue;
+    found[pkg] = { version, registry };
+  }
+  return found;
+}
+
+export function packageSourceOf(profileDir: string | null, pkg: string): InstalledSource | undefined {
+  return readInstalledSources(profileDir)[pkg];
+}
+
+function writeInstalledSources(profileDir: string, sources: InstalledSourceMap): void {
+  const file = installedSourcesFile(profileDir);
+  const temp = `${file}.tmp`;
+  const text = `${JSON.stringify({ version: FILE_VERSION, packages: sources }, null, 2)}\n`;
+  fs.writeFileSync(temp, text, { mode: 0o600 });
+  fs.renameSync(temp, file);
+}
+
+export function rememberPackageSource(profileDir: string, pkg: string, source: InstalledSource): void {
+  const trimmed = pkg.trim();
+  if (trimmed === '' || source.version.trim() === '' || source.registry.trim() === '') return;
+  const all = { ...readInstalledSources(profileDir) };
+  all[trimmed] = { version: source.version.trim(), registry: source.registry.trim() };
+  writeInstalledSources(profileDir, all);
+}
+
+export function forgetPackageSource(profileDir: string, pkg: string): void {
+  const all = { ...readInstalledSources(profileDir) };
+  if (all[pkg] === undefined) return;
+  delete all[pkg];
+  writeInstalledSources(profileDir, all);
+}

package/src/host/lib-install.ts

@@ -1,4 +1,5 @@
-import type { LibNeed, SupplySource } from '../contract/needs.js';
+import type { BinNeed, LibNeed, SupplySource } from '../contract/needs.js';
+import type { HostOs } from '../contract/protocol/platform.js';
 import { npmRegistryOf } from './plugin-source.js';
 import { quoteShellArg } from './shell-text.js';
 import { libsPrefix, npmCacheDir } from './paths.js';
@@ -9,10 +10,45 @@ export function libInstallCommand(options: {
   readonly need: LibNeed;
   readonly source: NpmSource;
   readonly version?: string | undefined;
+  readonly env?: NodeJS.ProcessEnv | undefined;
 }): string {
   const { need, source, version } = options;
-  const registry = npmRegistryOf(source, process.env);
+  const registry = npmRegistryOf(source, options.env ?? process.env);
   const spec = version ?? need.version ?? 'latest';
   const registryFlag = registry.ok ? ` --registry ${quoteShellArg(registry.value)}` : '';
   return `npm i --prefix ${quoteShellArg(libsPrefix())} ${quoteShellArg(`${need.name}@${spec}`)}${registryFlag} --cache ${quoteShellArg(npmCacheDir())}`;
 }
+
+/**
+ * 这个 bin 在这台机器上怎么装：作者写了 `install` 且平台对得上才给出那条命令。
+ * `command` 原样照抄；`npm` 装进隔离运行时的共用依赖前缀（那份包里的 bin 会自动上 PATH）。
+ * @param need 一条 bin 需要。
+ * @param os 宿主平台（由平台适配器给出）。
+ * @param env 取 registry 环境变量的地方。
+ * @returns 一条能直接粘进终端的命令；没声明或平台不对就是 undefined。
+ */
+export function binInstallCommand(
+  need: BinNeed,
+  os: HostOs,
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  const install = need.install;
+  if (install === undefined) return undefined;
+  if (install.platforms !== undefined && !install.platforms.includes(os)) return undefined;
+  if (install.kind === 'command') {
+    const line = install.line.trim();
+    return line === '' ? undefined : line;
+  }
+  const packageName = install.package.trim();
+  if (packageName === '') return undefined;
+  return libInstallCommand({
+    need: { kind: 'lib', name: packageName, purpose: need.purpose },
+    source: {
+      kind: 'npm',
+      package: packageName,
+      ...(install.registryEnv === undefined ? {} : { registryEnv: install.registryEnv }),
+      ...(install.registryDefault === undefined ? {} : { registryDefault: install.registryDefault }),
+    },
+    env,
+  });
+}

package/src/host/market-index-claim.ts

@@ -1,4 +1,5 @@
 import type { MarketClaim, MarketIndex, MarketIndexEntry } from '../contract/protocol/market-index.js';
+import { MARKET_ARTIFACTS_DIR } from '../contract/protocol/market-index.js';
 
 export interface PublisherIdentity {
   readonly name: string;
@@ -53,6 +54,14 @@ export function marketArtifactPath(name: string): string {
   return `packages/${name}`;
 }
 
+export function marketArtifactRoot(name: string): string {
+  return `${MARKET_ARTIFACTS_DIR}/${name}`;
+}
+
+export function marketArtifactPathFor(name: string, version: string): string {
+  return `${MARKET_ARTIFACTS_DIR}/${name}/${version}`;
+}
+
 export function entryUnitOf(entry: MarketIndexEntry): string | undefined {
   const unit = entry.metadata?.unit?.trim();
   if (unit !== undefined && unit !== '') return unit;

package/src/host/market-index-doc.ts

@@ -0,0 +1,62 @@
+import type {
+  MarketIndex,
+  MarketIndexEngines,
+  MarketIndexEntryMetadata,
+  MarketIndexProblem,
+  MarketIndexSource,
+  MarketLocalizedText,
+} from '../contract/protocol/market-index.js';
+
+export interface MarketVersionDoc {
+  readonly name: string;
+  readonly version: string;
+  readonly source: MarketIndexSource;
+  readonly publishTimestamp?: number;
+  readonly engines?: MarketIndexEngines;
+  readonly title?: MarketLocalizedText;
+  readonly description?: MarketLocalizedText;
+  readonly author?: string;
+  readonly owner?: string;
+  readonly homepage?: string;
+  readonly icon?: string;
+  readonly metadata?: MarketIndexEntryMetadata;
+}
+
+export interface MarketMetaDoc {
+  readonly name: string;
+  readonly epoch?: number;
+  readonly publishTimestamp: number;
+  readonly title?: MarketLocalizedText;
+  readonly description?: MarketLocalizedText;
+  readonly author?: string;
+  readonly owner?: string;
+  readonly homepage?: string;
+  readonly icon?: string;
+  readonly metadata?: MarketIndexEntryMetadata;
+}
+
+export type MarketEntryDoc = MarketVersionDoc | MarketMetaDoc;
+
+export type MarketEntryDocParse =
+  | { readonly ok: true; readonly doc: MarketEntryDoc }
+  | { readonly ok: false; readonly problems: readonly MarketIndexProblem[] };
+
+export interface MarketEntryFile {
+  readonly path: string;
+  readonly text: string;
+}
+
+export type MarketIndexAssemble =
+  | { readonly ok: true; readonly index: MarketIndex }
+  | { readonly ok: false; readonly problems: readonly MarketIndexProblem[] };
+
+export interface MarketDocFields {
+  readonly name: string;
+  readonly title?: MarketLocalizedText;
+  readonly description?: MarketLocalizedText;
+  readonly author?: string;
+  readonly owner?: string;
+  readonly homepage?: string;
+  readonly icon?: string;
+  readonly metadata?: MarketIndexEntryMetadata;
+}