@dsh-workbench/module-tools 0.3.11 → 1.0.0-beta.1

package/src/primitives-surface.mjs

@@ -1,33 +1,16 @@
-// dsh 原语本包的**可见面**：从装机那份类型面（`lib/types/**/*.d.ts`）取出导出名，按名字形状分桶。
-//
-// 为什么读类型面而不是源码：这个包发布出去的 `files` 只有
-// `lib/index.js` / `lib/**/*.css` / `lib/types/**/*.d.ts` —— **源码树不随包发布**
-// （`package.json` 的 `exports['./src/*']` 在装机包里是死条目），类型面是唯一机器可读的清单。
-//
-// 为什么不上 TypeScript API：module-tools 自己没有 `typescript` 依赖（只有 `typescript-eslint`
-// 的 peer），而这份 barrel 是 tsc 生成的、形状稳定：`export { A, B } from './X.tsx'` +
-// `export type { … }`（滤掉）+ 少量 `export declare const X` + 一条 `export *`（要跟着走）。
-// 代价是"上游换了 emit 形状没人知道"—— 由 selfcheck 那条"清单非空 / 含 Button / `Icon*Regular` ≥ 90"
-// 兜住（`.scratch/dsh-primitives-face/spec.md` §3.4 / §8.1）。
-//
-// 分桶**只按名字形状**，不判用途：`Icon*` → 图标；`^use[A-Z]` → hooks；首字母大写 → 组件；
-// 其余（常量、纯函数）→ 工具。"这件是不是该用、该怎么用"是判断，留给 agent / 人（TOOLING.md 那条口径）。
-
 import { existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 
 export const PRIMITIVES_SPECIFIER = '@deepseek-ai/dsh-client-ui-primitives';
 
-/** 从 `from`（一个包的目录）解析这个原语包；解析不到返回 undefined。 */
 export function installedPrimitives(from) {
   try {
     const require = createRequire(join(from, 'package.json'));
     const manifest = require.resolve(`${PRIMITIVES_SPECIFIER}/package.json`);
     const parsed = JSON.parse(readFileSync(manifest, 'utf8'));
     const version = typeof parsed.version === 'string' ? parsed.version : undefined;
-    // 打印/落点用它**从 node_modules 看**的那条路径（pnpm 把真身放在 `.pnpm/` 哈希目录里，
-    // `require.resolve` 给的是 realpath）—— agent 照着能直接打开，也短得多。
+
     const viaNodeModules = join(from, 'node_modules', ...PRIMITIVES_SPECIFIER.split('/'));
     const dir = existsSync(join(viaNodeModules, 'package.json')) ? viaNodeModules : dirname(manifest);
     return { manifest, dir, version };
@@ -36,7 +19,6 @@ export function installedPrimitives(from) {
   }
 }
 
-/** 外壳 manifest 里钉的那份原语版本（`devDependencies` 那一格）—— 模板盖章与漂移 note 都用它。 */
 export function pinnedPrimitivesVersion(manifestPath) {
   try {
     const pinned = JSON.parse(readFileSync(manifestPath, 'utf8')).devDependencies?.[PRIMITIVES_SPECIFIER];
@@ -46,12 +28,10 @@ export function pinnedPrimitivesVersion(manifestPath) {
   }
 }
 
-/** `export … from '…'` 一条条看：`export type` 滤掉、`export *` 跟着走、其余按名字拆。 */
 const STATEMENT = /export\s+(type\s+)?(\*|\{[^}]*\})\s*from\s*'([^']+)'/g;
 const DECLARED = /^export declare (?:const|function|class)\s+([A-Za-z_$][\w$]*)/gm;
 const MAX_STAR_DEPTH = 3;
 
-/** 说明符落到同目录的 `.d.ts`：`./icons/index.tsx` → `<types>/icons/index.d.ts`。 */
 function dtsTargetOf(fromFile, specifier) {
   const base = join(dirname(fromFile), specifier);
   const stripped = base.replace(/\.(tsx?|jsx?|mjs|cjs)$/, '');
@@ -84,18 +64,12 @@ function collect(file, origin, acc, depth) {
       if (target !== undefined) collect(target, origin, acc, depth + 1);
       continue;
     }
-    // 名字**声明**在哪份 `.d.ts`：`export { Button } from './Button.tsx'` 的答案就是
-    // `lib/types/Button.d.ts` —— 这条信息就是"agent 想用哪个直接去看"的落点，别丢。
+
     const declaredIn = dtsTargetOf(file, match[3]) ?? file;
     for (const name of namesOf(match[2])) acc.set(name, { origin, file: declaredIn });
   }
 }
 
-/**
- * 装机那份类型面的导出，按名字形状分成四桶。
- * `typesDir` = 原语包的 `lib/types`；读不到入口时抛（调用方给人话，不给空表）。
- * `files` = 名字 → 声明它的那份 `.d.ts` 的绝对路径（188 枚图标同指 `icons/index.d.ts`）。
- */
 export function surfaceOf(typesDir) {
   const entry = join(typesDir, 'index.d.ts');
   if (!existsSync(entry)) throw new Error(`类型面不在：${entry}`);

package/src/publish.mjs

@@ -1,30 +1,17 @@
-// 发货前那一张清单：门禁 + 三张表 + `npm pack --dry-run` 的清单。
-//
-// ── 为什么要有这个命令 ────────────────────────────────────────────────────────
-//
-// 打包这件事有两条**静默**的坑，都真发生过：
-//   · `files` 里漏一个目录（`template-diy/` 那次）：在仓里跑永远看不出问题，装出来的那份
-//     `init --template diy` 直接报"模板不存在"；
-//   · 产物/声明对不上（`exports` 指向的文件没被 `files` 带上）：装上去加载器找不到入口。
-// 两条都不会在开发时冒头，只会在"别人装到那一刻"炸。所以把它们变成发货前的一条命令。
-//
-// 这条命令**只做 dry run**：真发布要凭据、要人点头，不在这里做。它跑完会打印你该跑的那一条。
-
-import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { execaSync } from 'execa';
 
 import { DESIGN_FILE } from './design.mjs';
+import { publishTagOf } from './release-util.mjs';
 
-/** 门禁那几条命令自己会 `process.exit`（它们本来就是 CLI），所以这里**走子进程** ——
- *  直接 import 进来调，成功那次也会把整条 publish 结束掉（实测：清单还没打印就退出了）。 */
 const CLI = fileURLToPath(new URL('../bin/dsh-wb-module.mjs', import.meta.url));
 
 function runCli(root, argv) {
   try {
-    execFileSync(process.execPath, [CLI, ...argv, '--cwd', root], { stdio: 'inherit' });
+    execaSync(process.execPath, [CLI, ...argv, '--cwd', root], { stdio: 'inherit' });
   } catch {
     console.error(`✖ ${argv.join(' ')} 没过 —— 清单先不打印了，把上面那些红字处理掉`);
     process.exit(1);
@@ -37,13 +24,11 @@ function readManifest(root) {
 
 function packList(root) {
   const cache = join(tmpdir(), 'dsh-wb-pack-cache');
-  // `--ignore-scripts`：`prepack`（= build）会往 stdout 打自己的日志，和 `--json` 的输出混在一起
-  // 就没法 parse 了（实测）。反正上面已经自己 build 过一遍，这里不需要 npm 再跑一次。
-  const raw = execFileSync('npm', ['pack', '--dry-run', '--json', '--ignore-scripts', '--cache', cache], {
+
+  const raw = execaSync('npm', ['pack', '--dry-run', '--json', '--ignore-scripts', '--cache', cache], {
     cwd: root,
-    encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'pipe'],
-  });
+  }).stdout;
   const start = raw.search(/[[{]/);
   if (start === -1) throw new Error(`npm pack 没有输出 JSON：${raw.slice(0, 200)}`);
   const parsed = JSON.parse(raw.slice(start));
@@ -62,8 +47,7 @@ export async function publish({ root }) {
   const isModule = typeof unit === 'string' && unit !== '';
 
   if (isModule) {
-    // 先构建：清单评的是**要发出去的那份**，而 `npm pack` 自己也会跑 prepack（= build）——
-    // 不先构建就会拿"还没构建"的半成品去跑门禁，红得莫名其妙。
+
     runCli(root, ['build']);
     runCli(root, ['check']);
     if (existsSync(join(root, DESIGN_FILE))) runCli(root, ['design', 'check']);
@@ -100,7 +84,6 @@ export async function publish({ root }) {
   if (readmeOnDisk && !paths.includes('README.md')) problems.push('README.md 在盘上却没进包');
   if (!readmeOnDisk) console.log('○ 包根下没有 README.md —— 发出去的包在源上会是一页空白，建议补一份');
 
-  // `.tpl` 在 `template*/` 里是**本体**（init 拷过去才剥壳），只有在别处冒出来才算混进脏东西。
   const inTemplate = (one) => templateDirs.some((dir) => one.startsWith(`${dir}/`));
   const leftovers = paths.filter((one) => !inTemplate(one) && (one.endsWith('.tpl') || one.includes('.init-')));
   if (leftovers.length > 0) problems.push(`包里混进了不该发的东西：${leftovers.slice(0, 3).join('、')}`);
@@ -129,6 +112,9 @@ export async function publish({ root }) {
     return;
   }
   console.log('✔ 清单干净。真要发就自己跑（凭据在你手上）：');
-  console.log(`  npm publish${manifest.publishConfig?.registry === undefined ? '' : ` --registry ${manifest.publishConfig.registry}`}`);
+  const tag = publishTagOf(manifest.version);
+  console.log(
+    `  npm publish${manifest.publishConfig?.registry === undefined ? '' : ` --registry ${manifest.publishConfig.registry}`}${tag === undefined ? '' : ` --tag ${tag}`}`,
+  );
   console.log(`  包目录：${relative(process.cwd(), root) === '' ? '.' : relative(process.cwd(), root)}`);
 }

package/src/release-changelog.mjs

@@ -0,0 +1,29 @@
+import { changelogProblemOf } from './changelog.mjs';
+
+function manifestAuthor(manifest) {
+  const author = manifest?.author;
+  if (typeof author === 'string') return author.trim();
+  if (author !== null && typeof author === 'object' && typeof author.name === 'string') return author.name.trim();
+  return '';
+}
+
+function configValue(exec, root, key) {
+  const result = exec('git', ['-C', root, 'config', key], { capture: true, allowFailure: true });
+  return result.status === 0 ? result.stdout.trim() : '';
+}
+
+export function authorChangeOf(root, manifest, exec) {
+  if (manifestAuthor(manifest) !== '') return {};
+  const name = configValue(exec, root, 'user.name');
+  if (name === '') return {};
+  const email = configValue(exec, root, 'user.email');
+  return {
+    author: email === '' ? name : `${name} <${email}>`,
+    change: 'author ← git config',
+  };
+}
+
+export function changelogGateOf(root, version) {
+  const problem = changelogProblemOf(root, version);
+  return problem === undefined ? { ok: true } : { ok: false, ...problem };
+}

package/src/release-journal.mjs

@@ -0,0 +1,131 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const FINGERPRINT_FILES = [
+  'package.json',
+  'design.json',
+  'dist/host.js',
+  'client.js',
+  'cordis.patch.yml',
+  'README.md',
+  'CHANGELOG.md',
+];
+
+function statePathOf(home, unit) {
+  return join(home, 'workbench', 'releases', `${unit}.json`);
+}
+
+export function readState(home, unit) {
+  try {
+    return JSON.parse(readFileSync(statePathOf(home, unit), 'utf8'));
+  } catch {
+    return undefined;
+  }
+}
+
+export function writeState(home, unit, state) {
+  const file = statePathOf(home, unit);
+  mkdirSync(dirname(file), { recursive: true });
+  const temp = `${file}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(state, null, 2)}\n`);
+  renameSync(temp, file);
+}
+
+export function removeState(home, unit) {
+  try {
+    rmSync(statePathOf(home, unit));
+  } catch {
+    return;
+  }
+}
+
+export function artifactFingerprintOf(root) {
+  const hash = createHash('sha256');
+  for (const rel of FINGERPRINT_FILES) {
+    hash.update(`${rel}:`);
+    try {
+      hash.update(readFileSync(join(root, rel)));
+    } catch {
+      hash.update('missing');
+    }
+    hash.update('\n');
+  }
+  return hash.digest('hex').slice(0, 16);
+}
+
+export function resumableState(home, unit) {
+  const state = readState(home, unit);
+  if (state === undefined || typeof state !== 'object' || state === null) return undefined;
+  const run = state.run;
+  if (run === undefined || typeof run !== 'object' || run === null) return undefined;
+  if (run.state === 'done') return undefined;
+  return state;
+}
+
+export function startRun(home, unit, init) {
+  const current = readState(home, unit) ?? {};
+  const previous = current.run;
+  const resuming = init.resume === true && previous !== undefined;
+  const run = {
+    ...(resuming ? previous : {}),
+    id: resuming && typeof previous.id === 'string' ? previous.id : `run-${randomUUID()}`,
+    state: 'running',
+    phase: 'preflight',
+    attempts: resuming ? Number(previous.attempts ?? 0) + 1 : 0,
+    pid: process.pid,
+    startedAt: resuming && typeof previous.startedAt === 'string' ? previous.startedAt : new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    ...init.fields,
+  };
+  writeState(home, unit, {
+    ...current,
+    target: init.target,
+    name: init.name,
+    ...(init.version === undefined ? {} : { version: init.version }),
+    ...(typeof current.status === 'string' ? {} : { status: 'intent' }),
+    at: new Date().toISOString(),
+    run,
+  });
+  return run;
+}
+
+export function advanceRun(home, unit, patch) {
+  const current = readState(home, unit);
+  if (current === undefined || typeof current !== 'object' || current === null) return undefined;
+  const run = {
+    ...(current.run ?? {}),
+    ...patch,
+    pid: process.pid,
+    updatedAt: new Date().toISOString(),
+  };
+  writeState(home, unit, {
+    ...current,
+    ...(patch.version === undefined ? {} : { version: patch.version }),
+    ...(patch.status === undefined ? {} : { status: patch.status }),
+    run,
+  });
+  return run;
+}
+
+export function interruptRun(home, unit, failure) {
+  const current = readState(home, unit) ?? {};
+  const run = {
+    ...(current.run ?? {}),
+    state: 'interrupted',
+    ...(typeof failure.phase === 'string' ? { phase: failure.phase } : {}),
+    lastError: {
+      class: failure.class ?? 'transient',
+      code: failure.code ?? '',
+      text: failure.text ?? '',
+      at: new Date().toISOString(),
+    },
+    updatedAt: new Date().toISOString(),
+  };
+  writeState(home, unit, { ...current, run });
+  return run;
+}
+
+export function finishRun(home, unit, patch = {}) {
+  return advanceRun(home, unit, { ...patch, state: 'done' });
+}

package/src/release-report.mjs

@@ -0,0 +1,99 @@
+function httpsUrlOf(url) {
+  const text = String(url).trim();
+  if (!text.startsWith('git@')) return text;
+  const rest = text.slice(4);
+  const at = rest.indexOf(':');
+  if (at === -1) return text;
+  return `https://${rest.slice(0, at)}/${rest.slice(at + 1)}`;
+}
+
+function shortSha(value) {
+  return typeof value === 'string' && value.length >= 7 ? value.slice(0, 7) : String(value ?? '');
+}
+
+export function gitInstallSpecOf(info, version) {
+  const base = `git+${httpsUrlOf(info.url)}#${info.tagOf(version)}`;
+  return info.packagePath === '.' ? base : `${base}&path:/${info.packagePath}`;
+}
+
+export function marketInstallOf(url, commit, path) {
+  const base = `git+${httpsUrlOf(url)}#${commit}`;
+  const suffix = String(path ?? '').replace(/^\/+/, '');
+  return suffix === '' || suffix === '.' ? base : `${base}&path:/${suffix}`;
+}
+
+export function installOf(info, name, version) {
+  if (info.kind === 'tarball') return `dsh plugin --profile workbench add ${info.fileOf(version)}`;
+  if (info.kind === 'git') return `dsh plugin --profile workbench add ${gitInstallSpecOf(info, version)}`;
+  return `dsh plugin --profile workbench add ${name}@${version}`;
+}
+
+export function stateOf(info, manifest, version, status) {
+  const base = {
+    target: info.target,
+    name: manifest.name,
+    version,
+    status,
+    at: new Date().toISOString(),
+  };
+  if (info.kind === 'registry') base.registry = info.registry;
+  if (info.kind === 'tarball') base.file = info.fileOf(version);
+  if (info.kind === 'git') {
+    base.remote = info.url;
+    base.tag = info.tagOf(version);
+  }
+  return base;
+}
+
+export function emit(out, json, value) {
+  if (json) out(JSON.stringify(value));
+  else human(out, value);
+}
+
+export function human(out, summary) {
+  if (summary.target === 'local') {
+    out('没发，留在本机。');
+    return;
+  }
+  if (summary.dryRun === true) {
+    out(`○ 只到预览（dry-run）：${summary.name}@${summary.version} → ${summary.target}`);
+    if (summary.changes.length > 0) out(`  会改：${summary.changes.join('；')}`);
+    if (summary.files !== undefined) out(`  包内容：${summary.files.join(' · ')}`);
+    if (summary.market?.planned === true) out(`  会更新市场索引：${summary.market.url} → ${summary.market.entry}`);
+    if (summary.install !== '') out(`  安装：${summary.install}`);
+    out('  什么都没写');
+    return;
+  }
+  if (summary.target === 'market') {
+    const market = summary.market ?? {};
+    out(
+      `✔ 已发布 ${summary.name}@${summary.version} → ${market.url}` +
+        `（${market.branch === undefined ? '默认分支' : market.branch}）`,
+    );
+    out(`  产物：${String(market.path ?? '').replace(/^\/*/, '')} · commit ${shortSha(market.commit)}`);
+    out('  提交：产物与 market.json 两个 commit 都已推上去');
+    if (summary.changes.length > 0) out(`  改了：${summary.changes.join('；')}`);
+    if (summary.files !== undefined) out(`  包内容：${summary.files.join(' · ')}`);
+    out(`  安装：${summary.install}`);
+    out('  已从仓库侧核过产物');
+    return;
+  }
+  const where =
+    summary.target === 'tarball'
+      ? summary.file
+      : summary.target === 'git'
+        ? `${summary.git.url}（tag ${summary.git.tag}）`
+        : summary.registry;
+  out(`✔ 已发布 ${summary.name}@${summary.version} → ${where}`);
+  if (summary.changes.length > 0) out(`  改了：${summary.changes.join('；')}`);
+  if (summary.files !== undefined) out(`  包内容：${summary.files.join(' · ')}`);
+  if (summary.market !== undefined) {
+    out(
+      summary.market.updated === true
+        ? `  市场索引：${summary.market.url}${summary.market.branch === undefined ? '' : `（${summary.market.branch}）`} · ${summary.market.entry}`
+        : `  市场索引没更新：${summary.market.reason ?? '（未说明）'}`,
+    );
+  }
+  out(`  安装：${summary.install}`);
+  out('  已从出口侧核过包内容');
+}

package/src/release-util.mjs

@@ -0,0 +1,87 @@
+import { mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { execaSync } from 'execa';
+import semver from 'semver';
+
+export class ReleaseError extends Error {
+  constructor(message, code = 1) {
+    super(message);
+    this.name = 'ReleaseError';
+    this.code = code;
+  }
+}
+
+export class ResumableError extends ReleaseError {
+  constructor(message, resume) {
+    super(message, 4);
+    this.name = 'ResumableError';
+    this.resume = resume;
+  }
+
+  toJSON() {
+    return { ok: false, resumable: true, text: this.message, resume: this.resume };
+  }
+}
+
+export class NeedsUser extends Error {
+  constructor(step, text, command, extra = {}) {
+    super(text);
+    this.name = 'NeedsUser';
+    this.step = step;
+    this.text = text;
+    this.command = command;
+    this.extra = extra;
+  }
+
+  toJSON() {
+    return {
+      step: this.step,
+      text: this.text,
+      ...(this.command === undefined ? {} : { command: this.command }),
+      ...this.extra,
+    };
+  }
+}
+
+export function tailOf(text) {
+  return String(text ?? '')
+    .trim()
+    .split('\n')
+    .filter((one) => one.trim() !== '')
+    .slice(-6)
+    .join(' | ');
+}
+
+export function publishTagOf(version) {
+  const prerelease = semver.prerelease(String(version ?? '').trim());
+  if (prerelease === null) return undefined;
+  return typeof prerelease[0] === 'string' ? prerelease[0] : 'next';
+}
+
+export function defaultExec(command, argv, { cwd, capture = false, allowFailure = false } = {}) {
+  const cache = join(tmpdir(), 'dsh-wb-npm-cache');
+  const logs = join(tmpdir(), 'dsh-wb-npm-logs');
+  mkdirSync(cache, { recursive: true });
+  mkdirSync(logs, { recursive: true });
+  let result;
+  try {
+    result = execaSync(command, argv, {
+      cwd,
+      env: { ...process.env, npm_config_cache: cache, npm_config_logs_dir: logs },
+      reject: false,
+      stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+    });
+  } catch (error) {
+    if (allowFailure) return { status: 1, stdout: '', stderr: String(error) };
+    throw new ReleaseError(`跑不起 ${command}：${String(error)}`);
+  }
+  const status = result.exitCode ?? 1;
+  const stdout = typeof result.stdout === 'string' ? result.stdout : '';
+  const stderr = typeof result.stderr === 'string' ? result.stderr : '';
+  if (status !== 0 && !allowFailure) {
+    const text = tailOf(`${stdout}\n${stderr}`);
+    throw new ReleaseError(`${command} ${argv.join(' ')} 没过${text === '' ? '' : `：${text}`}`);
+  }
+  return { status, stdout, stderr };
+}