skillhelper 0.4.2

package/build/build-site.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// 官网落地页构建/开发脚本，结构对齐 build/build-web.mjs。
+// - 默认：vite build（生产构建，base='/SkillsHelper/'）
+// - --dev：vite（本地开发服务器，base='/'）
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, '..');
+const siteRoot = path.join(repoRoot, 'packages', 'site');
+const viteBin = path.join(repoRoot, 'node_modules', 'vite', 'bin', 'vite.js');
+
+if (!fs.existsSync(viteBin)) {
+  console.error(`[build:site] vite not found at ${viteBin}`);
+  console.error('[build:site] run npm install first.');
+  process.exit(127);
+}
+
+const isDev = process.argv.includes('--dev');
+const args = isDev ? [] : ['build'];
+
+const result = spawnSync(process.execPath, [viteBin, ...args], {
+  cwd: siteRoot,
+  stdio: 'inherit',
+  env: process.env,
+});
+
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

package/build/build-web.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, '..');
+const webRoot = path.join(repoRoot, 'packages', 'web');
+const viteBin = path.join(repoRoot, 'node_modules', 'vite', 'bin', 'vite.js');
+
+if (!fs.existsSync(viteBin)) {
+  console.error(`[build:web] vite not found at ${viteBin}`);
+  console.error('[build:web] run npm install first; GitHub/npm prepare should install dev dependencies before this script runs.');
+  process.exit(127);
+}
+
+const result = spawnSync(process.execPath, [viteBin, 'build'], {
+  cwd: webRoot,
+  stdio: 'inherit',
+  env: process.env,
+});
+
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

package/build/pack-smoke.mjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn, spawnSync } from 'node:child_process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, '..');
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'skillhelper-pack-smoke-'));
+const packDir = path.join(tempRoot, 'pack');
+const installRoot = path.join(tempRoot, 'install');
+const home = path.join(tempRoot, 'home');
+const childOutput = [];
+const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+
+fs.mkdirSync(packDir, { recursive: true });
+fs.mkdirSync(installRoot, { recursive: true });
+fs.mkdirSync(home, { recursive: true });
+
+function run(name, args, options = {}) {
+  console.log(`\n[pack-smoke] $ ${name} ${args.join(' ')}`);
+  const res = spawnSync(name, args, {
+    cwd: repoRoot,
+    stdio: options.capture ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+    env: options.env || process.env,
+    encoding: 'utf8',
+  });
+  if (res.status !== 0) {
+    if (options.capture) {
+      process.stdout.write(res.stdout || '');
+      process.stderr.write(res.stderr || '');
+    }
+    throw new Error(`${name} ${args.join(' ')} failed with exit ${res.status}`);
+  }
+  return res;
+}
+
+function write(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text);
+}
+
+async function getFreePort() {
+  return await new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      server.close(() => resolve(address.port));
+    });
+  });
+}
+
+async function waitForHealth(base, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let lastError = '';
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${base}/api/health`);
+      const text = await res.text();
+      if (res.ok) {
+        const body = JSON.parse(text);
+        if (body.ok === true) return body;
+      }
+      lastError = `${res.status}: ${text}`;
+    } catch (err) {
+      lastError = err.message;
+    }
+    await new Promise(resolve => setTimeout(resolve, 250));
+  }
+  throw new Error(`health check timed out: ${lastError}`);
+}
+
+async function waitForChildClose(child) {
+  if (child.exitCode != null || child.signalCode != null) return;
+  await new Promise(resolve => {
+    const timer = setTimeout(resolve, 2000);
+    child.once('close', () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+function assertTarballEntries(tarball) {
+  const res = run('tar', ['-tf', tarball], { capture: true });
+  const entries = res.stdout.trim().split(/\r?\n/).filter(Boolean);
+  assert.ok(entries.length > 0, 'tarball should not be empty');
+
+  const forbidden = entries.filter(entry =>
+    entry.includes('/node_modules/') ||
+    entry.includes('/.vite/') ||
+    entry.endsWith('/node_modules') ||
+    entry.endsWith('/.vite')
+  );
+  assert.deepEqual(forbidden, [], 'tarball must not contain node_modules or .vite cache');
+
+  for (const required of [
+    'package/packages/web/dist/index.html',
+    'package/packages/web/dist/favicon.ico',
+    'package/packages/web/dist/site.webmanifest',
+    'package/packages/web/public/favicon.ico',
+    'package/packages/server/src/index.mjs',
+    'package/packages/scanner/src/index.mjs',
+  ]) {
+    assert.ok(entries.includes(required), `tarball missing ${required}`);
+  }
+}
+
+async function assertInstalledCli(tarball) {
+  run('npm', ['install', '--prefix', installRoot, '--silent', '--omit=dev', tarball]);
+
+  const bin = path.join(installRoot, 'node_modules', '.bin', 'skillhelper');
+  const version = run(bin, ['--version'], { capture: true });
+  assert.match(version.stdout, new RegExp(`^skillhelper v${escapeRegExp(pkg.version)}`, 'm'));
+
+  write(path.join(home, '.hermes', 'skills', 'pack-smoke', 'SKILL.md'), `---
+name: pack-smoke
+description: Pack smoke skill
+---
+# Pack smoke skill
+`);
+  write(path.join(home, 'sources.yaml'), `limits:
+  maxFiles: 100
+  maxFileBytes: 1048576
+`);
+
+  const port = await getFreePort();
+  const base = `http://127.0.0.1:${port}`;
+  const env = {
+    ...process.env,
+    HOME: home,
+    SKILLHELPER_HOME: home,
+    SKILLHELPER_NO_OPEN: '1',
+    LOG_LEVEL: 'error',
+    PORT: String(port),
+  };
+  const child = spawn(bin, ['start', '--foreground'], {
+    cwd: installRoot,
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  child.stdout.on('data', data => childOutput.push(data.toString()));
+  child.stderr.on('data', data => childOutput.push(data.toString()));
+
+  try {
+    const health = await waitForHealth(base, 15000);
+    assert.equal(health.ok, true);
+    assert.equal(health.version, pkg.version);
+
+    const icon = await fetch(`${base}/favicon.ico`);
+    const bytes = Buffer.from(await icon.arrayBuffer());
+    assert.equal(icon.ok, true);
+    assert.equal((icon.headers.get('content-type') || '').split(';')[0], 'image/x-icon');
+    assert.deepEqual([...bytes.subarray(0, 4)], [0x00, 0x00, 0x01, 0x00]);
+  } catch (err) {
+    const tail = childOutput.join('').trim().split(/\r?\n/).slice(-60).join('\n');
+    throw new Error(`${err.message}\n\nCLI output:\n${tail}`);
+  } finally {
+    if (child.exitCode == null && child.signalCode == null) {
+      child.kill('SIGTERM');
+    }
+    await waitForChildClose(child);
+  }
+}
+
+async function main() {
+  try {
+    run('npm', ['pack', '--pack-destination', packDir]);
+    const tarballs = fs.readdirSync(packDir)
+      .filter(name => name.endsWith('.tgz'))
+      .map(name => path.join(packDir, name));
+    assert.equal(tarballs.length, 1, 'npm pack should create exactly one tarball');
+    const tarball = tarballs[0];
+
+    assertTarballEntries(tarball);
+    await assertInstalledCli(tarball);
+    console.log('\n[pack-smoke] PASS tarball contents + installed CLI smoke');
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+function escapeRegExp(text) {
+  return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+main().catch(err => {
+  console.error('\n[pack-smoke] FAIL');
+  console.error(err && err.stack || err);
+  process.exit(1);
+});

package/build/prepare-publish.mjs

@@ -0,0 +1,3 @@
+// prepare-publish.mjs - 保险空操作
+// 项目已不使用 workspace，直接发布即可
+console.log('[prepare-publish] No workspace dependencies to replace - project uses direct file paths');

package/build/verify.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, '..');
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'skillhelper-verify-'));
+const oldHome = process.env.SKILLHELPER_HOME;
+const oldUserHome = process.env.HOME;
+process.env.SKILLHELPER_HOME = path.join(tempRoot, 'home');
+process.env.HOME = process.env.SKILLHELPER_HOME;
+
+const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+const testFiles = [
+  'packages/scanner/test/scanner.test.mjs',
+  'packages/server/test/server.test.mjs',
+];
+
+function run(name, args) {
+  console.log(`\n[verify] $ ${name} ${args.join(' ')}`);
+  const res = spawnSync(name, args, {
+    cwd: repoRoot,
+    stdio: 'inherit',
+    env: process.env,
+  });
+  if (res.status !== 0) throw new Error(`${name} ${args.join(' ')} failed with exit ${res.status}`);
+}
+
+function write(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text);
+}
+
+async function main() {
+  try {
+    run('npm', ['run', 'build:web']);
+    run('npm', ['run', 'typecheck:web']);
+    run('npm', ['run', 'test:web']);
+    run('node', ['--test', ...testFiles]);
+
+    const skillRoot = path.join(process.env.HOME, '.hermes', 'skills');
+    write(path.join(skillRoot, 'demo', 'verify-skill', 'SKILL.md'), `---
+name: verify-skill
+description: Verify smoke skill
+triggers:
+  - verify smoke
+---
+# Verify smoke skill
+Use this item to prove the local server works.
+`);
+    write(path.join(process.env.SKILLHELPER_HOME, 'sources.yaml'), `sources:
+  hermes:
+    enabled: true
+    roots:
+      - ${JSON.stringify(skillRoot)}
+limits:
+  maxFiles: 100
+  maxFileBytes: 1048576
+`);
+
+    const { startServer } = await import(path.join(repoRoot, 'packages/server/src/index.mjs'));
+    const { app } = await startServer({ port: 0 });
+    const address = app.server.address();
+    const port = address.port;
+    const base = `http://127.0.0.1:${port}`;
+    console.log(`\n[verify] server listening on ${base}`);
+
+    try {
+      const health = await fetchJson(`${base}/api/health`);
+      assert.equal(health.ok, true);
+      assert.equal(health.items, 1);
+      assert.equal(health.version, pkg.version);
+
+      const skills = await fetchJson(`${base}/api/skills`);
+      assert.equal(skills.length, 1);
+      assert.equal(skills[0].name, 'verify-skill');
+      assert.equal(skills[0].raw, undefined, '/api/skills must strip raw content');
+
+      const detail = await fetchJson(`${base}/api/skills/${skills[0].id}`);
+      assert.match(detail.raw, /Verify smoke skill/);
+
+      const stats = await fetchJson(`${base}/api/stats`);
+      assert.equal(stats.total, 1);
+      assert.equal(stats.byBrand.hermes, 1);
+
+      const reload = await fetchJson(`${base}/api/reload`, { method: 'POST' });
+      assert.equal(reload.ok, true);
+      assert.equal(reload.items, 1);
+
+      const index = await fetchText(`${base}/`);
+      assert.match(index.body, /<div id="app"><\/div>/);
+      const jsMatch = index.body.match(/\/assets\/[^"']+\.js/);
+      const cssMatch = index.body.match(/\/assets\/[^"']+\.css/);
+      assert.ok(jsMatch, 'index.html should reference built JS asset');
+      assert.ok(cssMatch, 'index.html should reference built CSS asset');
+
+      const js = await fetchText(`${base}${jsMatch[0]}`);
+      assert.equal(js.contentType.split(';')[0], 'text/javascript');
+      assert.ok(js.body.length > 1000);
+
+      const css = await fetchText(`${base}${cssMatch[0]}`);
+      assert.equal(css.contentType.split(';')[0], 'text/css');
+      assert.ok(css.body.includes('topbar') || css.body.includes('sidebar') || css.body.includes('detail'));
+
+      const manifest = await fetchJson(`${base}/site.webmanifest`);
+      assert.equal(manifest.name, '呼哈哈-技能助手');
+      assert.ok(manifest.icons.some(icon => icon.sizes === '192x192'));
+      assert.ok(manifest.icons.some(icon => icon.sizes === '512x512'));
+
+      const favicon = await fetchBuffer(`${base}/favicon.ico`);
+      assert.equal(favicon.contentType.split(';')[0], 'image/x-icon');
+      assert.deepEqual([...favicon.body.subarray(0, 4)], [0x00, 0x00, 0x01, 0x00]);
+    } finally {
+      await app.close();
+    }
+
+    run('node', ['build/pack-smoke.mjs']);
+    console.log('\n[verify] PASS build + tests + HTTP/API/static/package smoke checks');
+  } finally {
+    if (oldHome == null) delete process.env.SKILLHELPER_HOME;
+    else process.env.SKILLHELPER_HOME = oldHome;
+    if (oldUserHome == null) delete process.env.HOME;
+    else process.env.HOME = oldUserHome;
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+async function fetchJson(url, init) {
+  const res = await fetch(url, init);
+  const text = await res.text();
+  assert.equal(res.ok, true, `${url} returned ${res.status}: ${text}`);
+  return JSON.parse(text);
+}
+
+async function fetchText(url, init) {
+  const res = await fetch(url, init);
+  const body = await res.text();
+  assert.equal(res.ok, true, `${url} returned ${res.status}: ${body.slice(0, 200)}`);
+  return { body, contentType: res.headers.get('content-type') || '' };
+}
+
+async function fetchBuffer(url, init) {
+  const res = await fetch(url, init);
+  const body = Buffer.from(await res.arrayBuffer());
+  assert.equal(res.ok, true, `${url} returned ${res.status}: ${body.toString('utf8', 0, 200)}`);
+  return { body, contentType: res.headers.get('content-type') || '' };
+}
+
+main().catch(err => {
+  console.error('\n[verify] FAIL');
+  console.error(err && err.stack || err);
+  process.exit(1);
+});

package/config/sources.example.yaml

@@ -0,0 +1,126 @@
+# SkillHelper sources.yaml
+#
+# This file is copied to ~/.config/skillhelper/sources.yaml by `npm run init`.
+# Paths support ~ expansion and simple glob expansion in roots.
+#
+# Environment overrides:
+# - SKILLHELPER_HOME: user data directory
+# - PORT: preferred HTTP port
+#
+# Safety:
+# - adapters only read files; they do not execute tools or commands
+# - MCP configs are redacted before entering raw/preview
+# - copy/open API calls only operate on scanned item ids, not arbitrary paths
+
+sources:
+  hermes:
+    enabled: true
+    roots:
+      - ~/.hermes/skills
+      - ~/.hermes/profiles/*/skills
+
+  claude-code:
+    enabled: true
+    roots:
+      - ~/.claude/skills
+
+  codex:
+    enabled: true
+    files:
+      - ~/.codex/AGENTS.md
+    roots: []
+    globs:
+      - AGENTS.md
+
+  cursor:
+    enabled: true
+    files: []
+    roots:
+      - ~/.cursor
+    globs:
+      - rules/**/*.{md,mdc}
+      - .cursorrules
+
+  mcp-config:
+    enabled: true
+    files:
+      - ~/.cursor/mcp.json
+      - ~/.codex/config.toml
+      - ~/Library/Application Support/Claude/claude_desktop_config.json
+      - ~/.hermes/config.yaml
+
+  hermes-plugin:
+    enabled: true
+    roots:
+      - ~/.hermes/plugins
+      - ~/.hermes/profiles/*/plugins
+
+  codex-plugin:
+    enabled: true
+    roots:
+      - ~/.codex/plugins/cache
+
+  project-runbook:
+    enabled: true
+    # Add your project roots here. The default scans ~/Project/*.
+    # Each root scans docs/RUNBOOK-*.md plus common AI-agent instruction files.
+    roots:
+      - ~/Project/*
+    globs:
+      - docs/RUNBOOK-*.md
+      - AGENTS.md
+      - CLAUDE.md
+      - .cursorrules
+      - .cursor/rules/**/*.{md,mdc}
+
+  skills:
+    enabled: true
+    roots:
+      - ~/skills
+      - ~/Skills
+    globs:
+      - '*.md'
+      - '*/SKILL.md'
+      - '**/SKILL.md'
+
+  mcp:
+    enabled: true
+    roots:
+      - ~/mcp
+      - ~/MCP
+    globs:
+      - '*.md'
+      - '*.json'
+      - '*.yaml'
+      - '*.yml'
+      - '**/manifest.*'
+
+  skill:
+    enabled: true
+    roots:
+      - ~/skill
+    globs:
+      - '*.md'
+      - '*/SKILL.md'
+      - '**/SKILL.md'
+
+  obsidian:
+    enabled: false
+    roots: []
+    tagFilter: '#skill'
+
+ui:
+  port: 11520
+  autoOpen: true
+  defaultEditor: cursor
+  groupBy: [editor, category, product]
+
+limits:
+  maxFiles: 5000
+  maxFileBytes: 1048576
+
+exclude:
+  - '**/node_modules/**'
+  - '**/.git/**'
+  - '**/dist/**'
+  - '**/.venv/**'