openone-workflow-kit 0.1.0

package/scripts/build-release.cjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+const {
+  assertCleanReleaseSource,
+  readReleaseSourceState,
+  releaseSourceManifestLines
+} = require('./release-source-state.cjs');
+
+const root = path.resolve(__dirname, '..');
+const dist = path.join(root, 'dist');
+const localNpmCache = path.join(dist, '.npm-cache');
+const localMiseCache = path.join(dist, '.mise-cache');
+const sourceState = readReleaseSourceState(root);
+
+assertCleanReleaseSource(sourceState);
+
+fs.rmSync(dist, { recursive: true, force: true });
+fs.mkdirSync(dist, { recursive: true });
+fs.mkdirSync(localNpmCache, { recursive: true });
+fs.mkdirSync(localMiseCache, { recursive: true });
+
+const packageJson = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+
+runNpm(['run', 'check', '--', '--skip-release-build']);
+
+const pack = runNpm(['pack', '--pack-destination', dist, '--json']);
+let packed;
+try {
+  packed = JSON.parse(pack.stdout)[0];
+} catch (error) {
+  throw new Error(`无法解析 npm pack 输出: ${pack.stdout}`);
+}
+
+const tarball = path.join(dist, packed.filename);
+const installSmokeRoot = path.join(dist, 'install-smoke');
+const installPrefix = path.join(installSmokeRoot, 'consumer');
+const installTarget = path.join(installSmokeRoot, 'target-workspace');
+
+fs.rmSync(installSmokeRoot, { recursive: true, force: true });
+fs.mkdirSync(installPrefix, { recursive: true });
+fs.mkdirSync(path.join(installTarget, 'docs'), { recursive: true });
+fs.mkdirSync(path.join(installTarget, 'app'), { recursive: true });
+fs.writeFileSync(path.join(installTarget, 'docs', 'business-overview.md'), '# Business overview\n');
+fs.writeFileSync(path.join(installTarget, 'app', 'package.json'), '{"dependencies":{"react":"latest"}}\n');
+
+runNpm(['install', '--prefix', installPrefix, '--no-audit', '--no-fund', tarball]);
+const installedPackageRoot = path.join(installPrefix, 'node_modules', packageJson.name);
+// The npm package intentionally excludes repository-only GitHub configuration.
+// Run the public package's own checks after installation to prove that all
+// packaged release assets remain self-consistent without relying on `.github/`.
+runNpm(['--prefix', installedPackageRoot, 'run', 'check']);
+// Invoke the installed CommonJS entry with Node instead of executing npm's
+// platform-specific .bin shim. This keeps the release smoke identical on
+// Linux, macOS and Windows runners.
+const installedEntry = path.join(
+  installedPackageRoot,
+  'bin',
+  'init-workspace.cjs'
+);
+run(process.execPath, [installedEntry, '--target', installTarget, '--tools', 'codex,trea,codebuddy', '--yes']);
+for (const rel of [
+  'AGENTS.md',
+  '.trae/instructions.md',
+  '.codebuddy/instructions.md',
+  'workflow/team-profile.yaml',
+  'workflow/INITIALIZATION_QUESTIONS.md'
+]) {
+  const file = path.join(installTarget, rel);
+  if (!fs.existsSync(file)) throw new Error(`发布包安装 smoke 缺少 ${rel}`);
+}
+
+const bytes = fs.readFileSync(tarball);
+const sha256 = crypto.createHash('sha256').update(bytes).digest('hex');
+const finalSourceState = readReleaseSourceState(root);
+assertCleanReleaseSource(finalSourceState);
+if (finalSourceState.commit !== sourceState.commit || finalSourceState.tree !== sourceState.tree) {
+  throw new Error('发布构建期间 source commit 或 source tree 发生变化；拒绝生成无法绑定 reviewed commit 的 manifest');
+}
+const manifest = [
+  '# 发布清单',
+  '',
+  `- package: ${packageJson.name}`,
+  `- version: ${packageJson.version}`,
+  `- license: ${packageJson.license}`,
+  `- tarball: ${packed.filename}`,
+  `- size: ${packed.size}`,
+  `- unpacked_size: ${packed.unpackedSize}`,
+  `- sha256: ${sha256}`,
+  ...releaseSourceManifestLines(sourceState),
+  '- install_smoke: passed',
+  '- installed_package_check: passed',
+  `- generated_at: ${new Date().toISOString()}`,
+  '',
+  '## 文件内容',
+  '',
+  ...packed.files.map((file) => `- ${file.path} (${file.size} bytes)`),
+  '',
+  '## 人工发布边界',
+  '',
+  '本清单由本地构建生成。创建远程仓库、git push、创建 tag、npm publish 或其他远程写入动作都必须由维护者手动执行。',
+  ''
+].join('\n');
+
+fs.rmSync(installSmokeRoot, { recursive: true, force: true });
+fs.rmSync(localNpmCache, { recursive: true, force: true });
+fs.rmSync(localMiseCache, { recursive: true, force: true });
+
+fs.writeFileSync(path.join(dist, 'RELEASE_MANIFEST.md'), manifest);
+console.log(manifest);
+
+function runNpm(args) {
+  // npm exposes the exact CLI entry while running an npm script. Invoking that
+  // entry with Node avoids .cmd resolution differences on Windows.
+  const npmExecPath = process.env.npm_execpath;
+  if (npmExecPath && fs.existsSync(npmExecPath)) {
+    return run(process.execPath, [npmExecPath, ...args]);
+  }
+  if (process.platform === 'win32') {
+    return run(process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', 'npm', ...args]);
+  }
+  return run('npm', args);
+}
+
+function run(cmd, args) {
+  const result = spawnSync(cmd, args, {
+    cwd: root,
+    encoding: 'utf8',
+    env: Object.assign({}, process.env, {
+      AGENT_WORKFLOW_SKIP_RELEASE_BUILD: '1',
+      npm_config_cache: localNpmCache,
+      MISE_CACHE_DIR: localMiseCache
+    })
+  });
+  if (result.status !== 0) {
+    throw new Error(`${cmd} ${args.join(' ')} 执行失败\nSTDOUT:\n${result.stdout}\nSTDERR:\n${result.stderr}`);
+  }
+  return result;
+}

package/scripts/release-source-state.cjs

@@ -0,0 +1,38 @@
+const { spawnSync } = require('child_process');
+
+function readReleaseSourceState(root) {
+  const commit = gitOutput(root, ['rev-parse', 'HEAD']);
+  const tree = gitOutput(root, ['rev-parse', 'HEAD^{tree}']);
+  const status = gitOutput(root, ['status', '--porcelain=v1', '--untracked-files=all']);
+  return Object.freeze({ commit, tree, status, dirty: status.length > 0 });
+}
+
+function assertCleanReleaseSource(state) {
+  if (!state || state.dirty || state.status) {
+    const detail = state && state.status ? `\n${state.status}` : '';
+    throw new Error(`发布构建只允许从 clean reviewed commit 生成；请先审查并提交本地变更，再重跑 npm run build:release${detail}`);
+  }
+}
+
+function releaseSourceManifestLines(state) {
+  assertCleanReleaseSource(state);
+  return [
+    `- source_commit: ${state.commit}`,
+    `- source_tree: ${state.tree}`,
+    '- source_dirty: false'
+  ];
+}
+
+function gitOutput(root, args) {
+  const result = spawnSync('git', args, { cwd: root, encoding: 'utf8' });
+  if (result.status !== 0) {
+    throw new Error(`git ${args.join(' ')} 执行失败: ${result.stderr || result.stdout}`);
+  }
+  return result.stdout.trim();
+}
+
+module.exports = {
+  assertCleanReleaseSource,
+  readReleaseSourceState,
+  releaseSourceManifestLines
+};

package/templates/AGENTS.template.md

@@ -0,0 +1,26 @@
+# Agent Workflow
+
+本工作区使用 OpenOne Workflow Kit 生成的个人开发者工作流。
+
+## 事实源
+
+- 项目配置：`workflow/team-profile.yaml`
+- Core 工作流：`workflow/core/`
+- 可复用能力：`workflow/core/capabilities/`
+- 工具 adapter：只作为生成的薄入口
+
+## 硬闸门
+
+- 功能分支闸门和实现阶段闸门通过前，不得修改业务代码。
+- 个人项目允许 agent 在范围明确且工作树已检查后执行本地分支命名、创建、commit、tag 和本地 merge。
+- 远程 push、release、部署、数据库写入和生产配置写入需要用户明确授权。
+- 进入实现阶段后，同仓多需求并行必须使用独立 worktree。
+- 缺失本地资料时，必须向用户索要或记录到 `workflow/INITIALIZATION_QUESTIONS.md`。
+
+## 工具策略
+
+只能使用当前工具自己的 adapter。不要承诺所有工具体验完全一致。
+
+## 开始
+
+先读取 `workflow/team-profile.yaml`，再按 `workflow/core/commands/` 执行对应阶段。

package/test/release-readiness.cjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const {
+  assertCleanReleaseSource,
+  readReleaseSourceState,
+  releaseSourceManifestLines
+} = require('../scripts/release-source-state.cjs');
+
+const root = path.resolve(__dirname, '..');
+const pkg = readJson('package.json');
+const failures = [];
+
+expect(pkg.name === 'openone-workflow-kit', 'package name must be openone-workflow-kit');
+expect(pkg.version === '0.1.0', 'package version must be 0.1.0');
+expect(pkg.private === false, 'package must be publishable');
+expect(pkg.license === 'Apache-2.0', 'package license must be Apache-2.0');
+expect(pkg.engines && pkg.engines.node === '>=18', 'Node.js support must start at 18');
+expect(pkg.publishConfig && pkg.publishConfig.access === 'public', 'npm access must be public');
+expect(
+  pkg.repository && pkg.repository.url === 'git+https://github.com/bluecoast1379/openone-workflow-kit.git',
+  'repository URL must point to the public GitHub repository'
+);
+expect(
+  pkg.homepage === 'https://github.com/bluecoast1379/openone-workflow-kit#readme',
+  'homepage must point to the repository README'
+);
+expect(
+  pkg.bugs && pkg.bugs.url === 'https://github.com/bluecoast1379/openone-workflow-kit/issues',
+  'bugs URL must point to GitHub Issues'
+);
+
+for (const required of [
+  'README.md',
+  'CHANGELOG.md',
+  'LICENSE',
+  'NOTICE',
+  'bin/',
+  'scripts/',
+  'workflow/',
+  'templates/',
+  'examples/',
+  'docs/',
+  'test/'
+]) {
+  expect(pkg.files.includes(required), `package files must include ${required}`);
+}
+
+for (const [name, relative] of Object.entries(pkg.bin || {})) {
+  const file = path.join(root, relative);
+  expect(fs.existsSync(file), `bin ${name} must exist at ${relative}`);
+  if (fs.existsSync(file)) {
+    expect(fs.readFileSync(file, 'utf8').startsWith('#!/usr/bin/env node'), `bin ${name} must have a Node.js shebang`);
+  }
+}
+
+const readme = fs.readFileSync(path.join(root, 'README.md'), 'utf8');
+for (const marker of [
+  './docs/assets/hero.svg',
+  './docs/assets/quick-demo.svg',
+  './docs/assets/architecture.svg',
+  '## 30 秒 Quick Demo',
+  'openone-workflow-kit@0.1.0',
+  'open-workflow-kit',
+  'business-agent'
+]) {
+  expect(readme.includes(marker), `README must include ${marker}`);
+}
+
+const manifest = readJson('docs/assets/visual-manifest.json');
+for (const asset of manifest.assets || []) {
+  const file = path.join(root, 'docs', 'assets', asset.file);
+  expect(fs.existsSync(file), `visual asset must exist: ${asset.file}`);
+  if (!fs.existsSync(file)) continue;
+  const content = fs.readFileSync(file);
+  const text = content.toString('utf8');
+  const svgStart = text.match(/<svg\b[^>]*>/);
+  expect(Boolean(svgStart), `${asset.file} must contain an SVG root`);
+  if (svgStart) {
+    expect(new RegExp(`width=["']${asset.width}["']`).test(svgStart[0]), `${asset.file} width must be ${asset.width}`);
+    expect(new RegExp(`height=["']${asset.height}["']`).test(svgStart[0]), `${asset.file} height must be ${asset.height}`);
+    expect(
+      new RegExp(`viewBox=["']0 0 ${asset.width} ${asset.height}["']`).test(svgStart[0]),
+      `${asset.file} viewBox must match its dimensions`
+    );
+  }
+  expect(content.length <= 250 * 1024, `${asset.file} must be no larger than 250 KB`);
+  expect(text.includes('<title'), `${asset.file} must include an accessible title`);
+  expect(text.includes('<desc'), `${asset.file} must include an accessible description`);
+  expect(
+    crypto.createHash('sha256').update(content).digest('hex') === asset.sha256,
+    `${asset.file} checksum must match visual-manifest.json`
+  );
+}
+
+const sourceCheckout = fs.existsSync(path.join(root, '.git'));
+if (sourceCheckout) {
+  const attributesFile = path.join(root, '.gitattributes');
+  expect(fs.existsSync(attributesFile), 'source checkout must pin release-evidence line endings');
+  if (fs.existsSync(attributesFile)) {
+    const attributes = fs.readFileSync(attributesFile, 'utf8');
+    expect(
+      /^\*\.svg\s+text\s+eol=lf$/m.test(attributes),
+      'source checkout must keep SVG checksum evidence on LF line endings'
+    );
+  }
+  const workflowFile = path.join(root, '.github', 'workflows', 'check.yml');
+  expect(fs.existsSync(workflowFile), 'source checkout must include .github/workflows/check.yml');
+  if (fs.existsSync(workflowFile)) {
+    const workflow = fs.readFileSync(workflowFile, 'utf8');
+    expect(/permissions:\s*\n\s+contents: read/.test(workflow), 'CI permissions must be read-only');
+    for (const action of workflow.matchAll(/uses:\s*([^\s]+)/g)) {
+      expect(/@[0-9a-f]{40}$/.test(action[1]), `CI action must be pinned by commit SHA: ${action[1]}`);
+    }
+    for (const expected of [
+      'Ubuntu / Node 18',
+      'Ubuntu / Node 20',
+      'Ubuntu / Node 22',
+      'Windows / Node 20',
+      'macOS / Node 20'
+    ]) {
+      expect(workflow.includes(expected), `CI matrix must include ${expected}`);
+    }
+  }
+}
+
+expect(fs.existsSync(path.join(root, 'docs', 'releases', 'v0.1.0.md')), 'v0.1.0 release notes must exist');
+const manualPublish = fs.readFileSync(path.join(root, 'docs', 'manual-publish.md'), 'utf8');
+for (const marker of [
+  'npm publish --access public',
+  'npm view openone-workflow-kit@0.1.0 gitHead',
+  'npm view openone-workflow-kit@0.1.0 dist.shasum',
+  'dist/openone-workflow-kit-0.1.0.tgz',
+  'dist/RELEASE_MANIFEST.md'
+]) {
+  expect(manualPublish.includes(marker), `manual publish guide must include ${marker}`);
+}
+expect(!manualPublish.includes('npm publish ./dist/'), 'npm publication must run from the clean reviewed commit directory');
+verifyReleaseSourceBinding();
+
+if (failures.length) {
+  for (const failure of failures) console.error(`- ${failure}`);
+  process.exit(1);
+}
+
+console.log('Release readiness checks passed.');
+
+function readJson(relative) {
+  return JSON.parse(fs.readFileSync(path.join(root, relative), 'utf8'));
+}
+
+function expect(condition, message) {
+  if (!condition) failures.push(message);
+}
+
+function verifyReleaseSourceBinding() {
+  const fixture = fs.mkdtempSync(path.join(os.tmpdir(), 'openone-release-source-'));
+  try {
+    runGit(fixture, ['init']);
+    runGit(fixture, ['config', 'user.name', 'OpenOne Release Test']);
+    runGit(fixture, ['config', 'user.email', 'release-test@example.invalid']);
+    fs.writeFileSync(path.join(fixture, 'fixture.txt'), 'reviewed\n');
+    runGit(fixture, ['add', 'fixture.txt']);
+    runGit(fixture, ['-c', 'commit.gpgsign=false', 'commit', '-m', 'Create reviewed fixture']);
+
+    const clean = readReleaseSourceState(fixture);
+    expect(clean.dirty === false && clean.status === '', 'release source preflight must accept a clean commit');
+    expect(/^[0-9a-f]{40,64}$/.test(clean.commit), 'release source preflight must capture the source commit');
+    expect(/^[0-9a-f]{40,64}$/.test(clean.tree), 'release source preflight must capture the source tree');
+    expect(
+      JSON.stringify(releaseSourceManifestLines(clean)) === JSON.stringify([
+        `- source_commit: ${clean.commit}`,
+        `- source_tree: ${clean.tree}`,
+        '- source_dirty: false'
+      ]),
+      'release manifest must bind the clean source commit and tree'
+    );
+
+    fs.writeFileSync(path.join(fixture, 'unreviewed.txt'), 'dirty\n');
+    const dirty = readReleaseSourceState(fixture);
+    let rejected = false;
+    try {
+      assertCleanReleaseSource(dirty);
+    } catch (error) {
+      rejected = /clean reviewed commit/.test(String(error && error.message));
+    }
+    expect(dirty.dirty === true && dirty.status.includes('unreviewed.txt'), 'release source preflight must detect untracked changes');
+    expect(rejected, 'release source preflight must reject a dirty worktree');
+
+    fs.rmSync(path.join(fixture, 'unreviewed.txt'));
+    fs.writeFileSync(path.join(fixture, 'fixture.txt'), 'modified after review\n');
+    const modified = readReleaseSourceState(fixture);
+    let modifiedRejected = false;
+    try {
+      assertCleanReleaseSource(modified);
+    } catch (error) {
+      modifiedRejected = /clean reviewed commit/.test(String(error && error.message));
+    }
+    expect(modified.dirty === true && modified.status.includes('fixture.txt'), 'release source preflight must detect tracked changes');
+    expect(modifiedRejected, 'release source preflight must reject tracked changes');
+  } finally {
+    fs.rmSync(fixture, { recursive: true, force: true });
+  }
+}
+
+function runGit(cwd, args) {
+  const result = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  if (result.status !== 0) {
+    throw new Error(`git ${args.join(' ')} failed: ${result.stderr || result.stdout}`);
+  }
+}