skillcaddy 0.27.0

package/server.js

@@ -0,0 +1,196 @@
+import http from 'node:http';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  disableSkill,
+  ensureSourceFolders,
+  getState
+} from './lib/skillStore.js';
+import { syncClaudeSkills, unlinkClaudeSkill, unlinkClaudeSkills } from './lib/claudeStore.js';
+import { executeCollectionEnablement } from './lib/collectionEnablement.js';
+import { resolveRoots } from './lib/roots.js';
+import { readVersion } from './lib/version.js';
+import { enableProjectSkill } from './lib/projectActions.js';
+import { buildCollectionEnablePlan } from './lib/enablePlan.js';
+import { updateSkillMetadata } from './lib/skillMetadata.js';
+import { normalizeEnablementScope } from './lib/enablementScope.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// 代码根 = server.js 所在目录；原件库根由 SKILLCADDY_ROOT 指定，或按代码根推导。
+const roots = resolveRoots({ codeRoot: __dirname });
+const rootDir = roots.libraryRoot;
+const publicDir = path.join(roots.codeRoot, 'public');
+const port = Number(process.env.PORT || 4173);
+
+await ensureSourceFolders(roots);
+const appInfo = await readVersion(roots);
+
+const mimeTypes = {
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8'
+};
+
+const server = http.createServer(async (req, res) => {
+  try {
+    const url = new URL(req.url || '/', `http://${req.headers.host}`);
+
+    if (url.pathname.startsWith('/api/')) {
+      await handleApi(req, res, url);
+      return;
+    }
+
+    await serveStatic(res, url.pathname);
+  } catch (error) {
+    sendJson(res, 500, { error: error.message || 'Internal server error' });
+  }
+});
+
+server.listen(port, '127.0.0.1', () => {
+  console.log(`Skillcaddy: http://127.0.0.1:${port}`);
+});
+
+async function handleApi(req, res, url) {
+  if (req.method === 'GET' && url.pathname === '/api/version') {
+    sendJson(res, 200, appInfo);
+    return;
+  }
+
+  if (req.method === 'GET' && url.pathname === '/api/state') {
+    const projectPath = url.searchParams.get('projectPath') || rootDir;
+    sendJson(res, 200, await getState(roots, projectPath));
+    return;
+  }
+
+  if (req.method === 'POST' && url.pathname === '/api/enable') {
+    const body = await readJson(req);
+    const scope = requireApiScope(body);
+    requireProjectForScope(body, scope);
+    sendJson(res, 200, await enableProjectSkill(roots, {
+      scope,
+      ...(scope === 'project' ? { projectPath: body.projectPath } : {}),
+      skillPath: body.skillPath,
+      alias: body.alias
+    }));
+    return;
+  }
+
+  if (req.method === 'POST' && url.pathname === '/api/enable-plan') {
+    const body = await readJson(req);
+    const scope = requireApiScope(body);
+    requireProjectForScope(body, scope);
+    const state = await getState(roots, body.projectPath || rootDir);
+    sendJson(res, 200, buildCollectionEnablePlan(
+      state,
+      Array.isArray(body.skillIds) ? body.skillIds : [],
+      { scope }
+    ));
+    return;
+  }
+
+  if (req.method === 'POST' && url.pathname === '/api/enable-collection') {
+    const body = await readJson(req);
+    const scope = requireApiScope(body);
+    requireProjectForScope(body, scope);
+    sendJson(res, 200, await executeCollectionEnablement(roots, {
+      scope,
+      ...(body.projectPath ? { projectPath: body.projectPath } : {}),
+      skillIds: body.skillIds
+    }));
+    return;
+  }
+
+  if (req.method === 'POST' && url.pathname === '/api/skill-metadata') {
+    const body = await readJson(req);
+    sendJson(res, 200, await updateSkillMetadata(roots, body));
+    return;
+  }
+
+  if (req.method === 'POST' && url.pathname === '/api/disable') {
+    const body = await readJson(req);
+    const scope = requireApiScope(body);
+    requireProjectForScope(body, scope);
+    sendJson(res, 200, await disableSkill({
+      scope,
+      roots,
+      ...(scope === 'project' ? { projectPath: body.projectPath } : {}),
+      alias: body.alias
+    }));
+    return;
+  }
+
+  if (req.method === 'POST' && url.pathname === '/api/sync-claude') {
+    const body = await readJson(req);
+    sendJson(res, 200, await syncClaudeSkills(body.projectPath));
+    return;
+  }
+
+  if (req.method === 'POST' && url.pathname === '/api/unlink-claude') {
+    const body = await readJson(req);
+    sendJson(res, 200, await unlinkClaudeSkills(body.projectPath));
+    return;
+  }
+
+  if (req.method === 'POST' && url.pathname === '/api/unlink-claude-skill') {
+    const body = await readJson(req);
+    sendJson(res, 200, await unlinkClaudeSkill(body));
+    return;
+  }
+
+  sendJson(res, 404, { error: 'Not found' });
+}
+
+async function serveStatic(res, pathname) {
+  const requestPath = pathname === '/' ? '/index.html' : pathname;
+  const normalized = path.normalize(requestPath).replace(/^(\.\.[/\\])+/, '');
+  const filePath = path.join(publicDir, normalized);
+
+  if (!filePath.startsWith(publicDir)) {
+    sendJson(res, 403, { error: 'Forbidden' });
+    return;
+  }
+
+  try {
+    const file = await readFile(filePath);
+    res.writeHead(200, {
+      'Content-Type': mimeTypes[path.extname(filePath)] || 'application/octet-stream'
+    });
+    res.end(file);
+  } catch {
+    sendJson(res, 404, { error: 'Not found' });
+  }
+}
+
+async function readJson(req) {
+  const chunks = [];
+  for await (const chunk of req) {
+    chunks.push(chunk);
+  }
+
+  if (chunks.length === 0) {
+    return {};
+  }
+
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+
+function sendJson(res, status, payload) {
+  res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+  res.end(JSON.stringify(payload));
+}
+
+function requireApiScope(body) {
+  if (!body || !Object.hasOwn(body, 'scope')) {
+    throw new Error('scope 必须显式指定为 project、global 或 hermes');
+  }
+  return normalizeEnablementScope(body.scope);
+}
+
+function requireProjectForScope(body, scope) {
+  if (scope === 'project' && (!body.projectPath || typeof body.projectPath !== 'string')) {
+    throw new Error('project scope 需要 projectPath');
+  }
+}

package/skills/skillcaddy-manager/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: skillcaddy-manager
+description: Manage Skillcaddy source acquisition, source updates, migrations, project skill links, and the Web/TUI CLI. Use for discovery, add/update requests, enable/disable, audits, maintenance, bootstrap, or Web/TUI access.
+---
+
+# Skillcaddy Manager
+
+Treat Skillcaddy as a central skill library with explicit project/global/Hermes symlink activation. Keep one execution loop across every branch: **state -> route -> preflight -> act -> verify**.
+
+## Core Loop
+
+1. Resolve the Skillcaddy repository and target project. Default the project to the current working directory only when the user did not provide one.
+   - Complete when both absolute paths are known.
+2. For recommendations, audits, or mutations, read `GET /api/state?projectPath=<encoded-path>`. For source acquisition, updates, or migration, also inspect the source registry with `npm run source -- list` and `npm run source -- inspect <source-id>`. If the server is unavailable, inspect the equivalent paths listed under **Core Model**.
+   - Complete when repository, source registry, project, global, Hermes, Claude, metadata, and `advice` state relevant to the request are known.
+3. Route to the required branch and load only its reference; load multiple references only when the request combines branches:
+   - Discovery, source acquisition/update/migration, enable/disable, audit, health, Git update, bootstrap, Web/TUI: [OPERATIONS.md](references/OPERATIONS.md)
+   - Recommendations: [RECOMMENDATION_GUIDE.md](references/RECOMMENDATION_GUIDE.md)
+   - Notes, tags, `autoEnable`, migration, batch Chinese notes: [METADATA.md](references/METADATA.md)
+   - Complete when the selected branch, target identities, and completion criterion are explicit.
+4. For a mutation, apply the **Mutation Gate** before acting. Prefer the existing API, TUI, or repository commands over ad hoc filesystem changes.
+   - Complete when the preflight accounts for every affected item and all blocking ownership or alias issues are resolved.
+5. Execute the narrowest requested operation, rescan state, and report the observed result.
+   - Complete when the post-operation state proves every requested item succeeded, remained unchanged, was skipped, or failed with a stated reason.
+
+## Core Model
+
+| Scope | Location | Role |
+|---|---|---|
+| Bundled | `skills/<name>/` | Skills shipped by this repository |
+| Central | `official/`, `github/`, `personal/`, `archived/` | Source libraries |
+| Source registry | `.skillcaddy/sources/` | Sidecar identity, provenance, integrity, install path, and discovered skill paths |
+| Project | `<project>/.agents/skills/` | Codex-compatible activation symlinks |
+| Project Claude | `<project>/.claude/skills/` | Claude compatibility symlinks |
+| Global Agents | `~/.agents/skills/` | Shared user-level links managed by Skillcaddy |
+| Global Claude | `~/.claude/skills/` | Read-only external Agent directory; Skillcaddy does not write it |
+| Hermes | `~/.hermes/skills/` | Explicit independent scope for eligible `official`/`github`/`personal` sources |
+| Collection setup | `collection-metadata/<source>/<collection>.json` | Tracked, read-only setup contract and readiness checks |
+
+Preserve these invariants:
+
+- Enable and disable operations are explicit about `project` or `global` scope; source skill directories remain intact.
+- Project enablement writes `<project>/.agents/skills/` and best-effort syncs project Claude links. Global enablement writes only `~/.agents/skills/` and does not require a project.
+- Project and global aliases may coexist; project state is the higher-priority context when an Agent applies its normal precedence rules.
+- Never take over an occupied ordinary entry, foreign symlink, or broken link. Same-target enablement is an unchanged result.
+- Global disable may remove only a symlink whose target is provably inside the current Skillcaddy root's allowed source folders; foreign links and ordinary entries are read-only.
+- Source acquisition changes only the central library. It never implies enablement, setup, or execution of acquired code.
+- `add` is for a new source identity. Only a matching source-registry record authorizes `update`; a destination collision never does.
+- An explicit combined request runs acquisition first, rescans state, resolves one requested acquired skill, and enables only that selection.
+- Unknown setup readiness produces no reminder or gate. Declared setup reminders remain non-blocking; publisher runtime preflight owns proprietary credentials and setup.
+- `archived/` skills require an explicit user request.
+- GitHub-backed source directories remain free of Skillcaddy metadata; write catalog metadata to the sidecar store.
+- Collection activation and project readiness are separate: setup may be missing after links are enabled.
+- Interactive setup is never executed silently; obtain confirmation and let the declared setup skill own project edits.
+- Repository behavior in `lib/skillStore.js`, `lib/projectActions.js`, and `lib/claudeStore.js` is authoritative when documentation and implementation differ.
+- The fixed default Web manager URL is `http://127.0.0.1:4173`.
+- The clone-backed `skillcaddy` entry keeps no-argument TUI compatibility and also supports `start`, `stop`, `restart`, `-u` for registered Git source updates, and read-only `-a` analysis.
+- Global bootstrap is explicit: run `npm run install:cli` and `npm run check:cli` from the clone; the installed command provides both CLI and TUI, while `install:tui` remains a compatibility alias.
+- Source update and repair CLIs require an explicit `--project`; global links are always scanned in addition to that project context.
+- If a registered Git checkout was manually advanced with `git pull`, use `npm run source -- repair <source-id> --project <project-dir>` to explicitly adopt the clean fast-forward state into the sidecar registry; never edit the registry directly.
+
+## Mutation Gate
+
+Before changing state, present a compact preflight containing:
+
+| Action | Skill | Source/collection | Alias | Target path | Advice/result |
+|---|---|---|---|---|---|
+
+Account for skills that will be changed, left unchanged, skipped, or rejected. Include relevant `/api/state.advice` and metadata writes.
+
+Require confirmation before proceeding when:
+
+- one request matches multiple skills and the user has not selected one;
+- a project or global alias points to a different target;
+- a project or global entry is not a symlink or is externally managed;
+- a GitHub source has uncommitted changes before update;
+- a breaking source replacement affects a known project or global link;
+- a source identity is ambiguous or a destination collision is not backed by a matching registry record;
+- the request reaches into `archived/` without naming the archived target;
+- the request would delete a source skill rather than a project link;
+- an advice item exposes a destructive or ownership ambiguity.
+- an affected collection reports missing or partial interactive setup.
+
+Surface informational duplicate-name and global-shadowing advice, but do not block solely on it. Use the full skill ID and a confirmed alias to resolve duplicates.
+
+## Reporting
+
+For summaries, distinguish repository availability, project enablement, global presence, Claude compatibility, and unmanaged or broken state. Prefer:
+
+| Action | Skill | Source | Alias | Result | Notes |
+|---|---|---|---|---|---|
+
+End with the verification performed: rescan/API state, validation command, tests, or server URL.

package/skills/skillcaddy-manager/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Skillcaddy Manager"
+  short_description: "Manage project, global, and Hermes skills."
+  default_prompt: "Use $skillcaddy-manager to audit project/global/Hermes skills, review capability overlaps, and enable or disable skills safely."
+
+policy:
+  allow_implicit_invocation: true

package/skills/skillcaddy-manager/references/METADATA.md

@@ -0,0 +1,75 @@
+# Skillcaddy Metadata
+
+Use this reference for notes, tags, `autoEnable`, legacy migration, and batch Chinese note generation.
+
+## Storage Contract
+
+`SKILL.md` is the agent-facing execution contract. Skillcaddy catalog metadata is human-facing and lives at:
+
+```text
+.skillcaddy/metadata/<source>/<relative-skill-path>/skillcaddy.json
+```
+
+Since v0.15.0, runtime scans ignore legacy `<skill-dir>/skillcaddy.json`. The migration command explicitly discovers those files, remains through v0.15.x, and is removed in v0.16.0. New writes use the API or sidecar path, especially for GitHub-backed sources.
+
+Supported shape:
+
+```json
+{
+  "note": "简短、面向用户的用途说明。",
+  "tags": ["Developer Tools", "Productivity"],
+  "autoEnable": true
+}
+```
+
+Apply these rules:
+
+- Describe what the skill helps with; keep trigger logic in `SKILL.md`.
+- Use 1-4 broad, reusable product-style tags.
+- Preserve existing tags and `autoEnable` unless the request changes them or they are demonstrably wrong.
+- Set `autoEnable: false` for deprecated, risky, heavyweight, or highly situational skills that should be skipped by collection-level enablement.
+- Keep external GitHub clones clean; never add catalog metadata inside them.
+
+## Write Metadata
+
+Prefer the API:
+
+```bash
+curl -sS -X POST http://127.0.0.1:4173/api/skill-metadata \
+  -H 'Content-Type: application/json' \
+  -d '{"skillPath":"/path/to/skill","note":"简短说明","tags":["Developer Tools"],"autoEnable":true}'
+```
+
+Run the mutation gate from `SKILL.md`, then rescan `/api/state`. Complete when the response and rescan show the intended sidecar values and unrelated fields are unchanged.
+
+## Migrate Legacy Metadata
+
+Preview first, then obtain explicit confirmation before applying:
+
+```bash
+npm run migrate:metadata
+npm run migrate:metadata -- --yes
+```
+
+Migration writes equivalent sidecar metadata and retains the legacy file for rollback. Complete when a rescan uses the sidecar and no source metadata was removed.
+
+## Batch Chinese Notes
+
+Run commands from the Skillcaddy repository root. The script performs filesystem and API operations; the agent supplies the Chinese notes.
+
+```bash
+# 1. Produce a manifest bound to this library root.
+node skills/skillcaddy-manager/scripts/translate-skill-notes.cjs list --project=. > /tmp/skill-note-manifest.json
+
+# 2. Fill each manifest entry's note; retain schemaVersion and libraryRoot.
+
+# 3. Preflight without writes.
+node skills/skillcaddy-manager/scripts/translate-skill-notes.cjs apply /tmp/skill-note-manifest.json --project=.
+
+# 4. Apply only after reviewing the preflight.
+node skills/skillcaddy-manager/scripts/translate-skill-notes.cjs apply /tmp/skill-note-manifest.json --project=. --yes
+```
+
+Generate one short Chinese sentence per note. Leave `tags` and `autoEnable` unset to preserve their current values. Existing notes remain protected; use `--force-rewrite` only after explicit confirmation. The manifest's `schemaVersion` and `libraryRoot` must remain unchanged.
+
+If the API is unavailable, start `npm start`. Complete when preflight validates every entry before the first write, the applied count matches the intended manifest entries, and `/api/state` returns the new sidecar notes.