skillshark 0.1.0

package/src/discover.js

@@ -0,0 +1,298 @@
+// Local artifact discovery + metadata inference. Authors never write a
+// manifest; everything is inferred at share time (§4.1).
+import { readdir, readFile, stat, lstat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { sha256hex } from './fingerprint.js';
+import { CliError } from './errors.js';
+
+// Never packaged, not even with --force.
+const HARD_EXCLUDE_DIRS = new Set(['.git', 'node_modules']);
+const HARD_EXCLUDE_FILES = [/^\.DS_Store$/, /\.log$/i];
+// Secret-shaped: skipped with a warning; --force includes them.
+const SECRET_PATTERNS = [
+  { re: /^\.env$/, label: 'secret pattern' },
+  { re: /^\.env\..+$/, label: 'secret pattern' },
+  { re: /\.pem$/i, label: 'secret pattern' },
+  { re: /^id_rsa/, label: 'secret pattern' },
+  { re: /token/i, label: 'secret pattern' },
+  { re: /secret/i, label: 'secret pattern' },
+];
+const RESERVED_NAMES = new Set(['skillshark.json']);
+
+function hardExcluded(name) {
+  return HARD_EXCLUDE_FILES.some((re) => re.test(name));
+}
+
+function secretMatch(name) {
+  return SECRET_PATTERNS.find((p) => p.re.test(name)) ?? null;
+}
+
+// --- share-argument resolution (§4.1) ---------------------------------------
+
+// Candidate locations for a bare name, in search order.
+export function nameCandidates(name, { cwd, home }) {
+  return [
+    { root: path.join(cwd, '.claude', 'skills', name), isDir: true, type: 'skill', where: '.claude/skills (project)' },
+    { root: path.join(cwd, '.claude', 'commands', `${name}.md`), isDir: false, type: 'command', where: '.claude/commands (project)' },
+    { root: path.join(home, '.claude', 'skills', name), isDir: true, type: 'skill', where: '~/.claude/skills (global)' },
+    { root: path.join(home, '.claude', 'commands', `${name}.md`), isDir: false, type: 'command', where: '~/.claude/commands (global)' },
+  ];
+}
+
+async function existsAs(p, wantDir) {
+  try {
+    const s = await stat(p);
+    return wantDir ? s.isDirectory() : s.isFile();
+  } catch {
+    return false;
+  }
+}
+
+// Classify an explicit path by its on-disk convention (§4.1): a directory under
+// .claude/skills → skill, a .md under .claude/commands → command, otherwise
+// prompt (file) or bundle (directory).
+export function classifyPath(absPath, isDir) {
+  const norm = absPath.split(path.sep).join('/');
+  if (isDir && /\/\.claude\/skills\/[^/]+$/.test(norm)) return { type: 'skill', agent: 'claude-code' };
+  if (!isDir && /\/\.claude\/commands\/[^/]+\.md$/.test(norm)) return { type: 'command', agent: 'claude-code' };
+  return { type: isDir ? 'bundle' : 'prompt', agent: '' };
+}
+
+// List every skill/command name visible from here (for suggestions).
+export async function knownNames({ cwd, home }) {
+  const names = new Set();
+  for (const dir of [
+    path.join(cwd, '.claude', 'skills'),
+    path.join(home, '.claude', 'skills'),
+  ]) {
+    try {
+      for (const ent of await readdir(dir, { withFileTypes: true })) {
+        if (ent.isDirectory()) names.add(ent.name);
+      }
+    } catch { /* location absent */ }
+  }
+  for (const dir of [
+    path.join(cwd, '.claude', 'commands'),
+    path.join(home, '.claude', 'commands'),
+  ]) {
+    try {
+      for (const ent of await readdir(dir, { withFileTypes: true })) {
+        if (ent.isFile() && ent.name.endsWith('.md')) names.add(ent.name.slice(0, -3));
+      }
+    } catch { /* location absent */ }
+  }
+  return [...names].sort();
+}
+
+function editDistance(a, b) {
+  const m = a.length, n = b.length;
+  const d = Array.from({ length: m + 1 }, (_, i) => [i, ...Array(n).fill(0)]);
+  for (let j = 0; j <= n; j++) d[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      d[i][j] = Math.min(
+        d[i - 1][j] + 1,
+        d[i][j - 1] + 1,
+        d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+  }
+  return d[m][n];
+}
+
+export function nearestNames(name, candidates, max = 3) {
+  return candidates
+    .map((c) => ({ c, d: editDistance(name.toLowerCase(), c.toLowerCase()) }))
+    .filter(({ c, d }) => d <= 3 || c.toLowerCase().includes(name.toLowerCase()))
+    .sort((a, b) => a.d - b.d)
+    .slice(0, max)
+    .map(({ c }) => c);
+}
+
+// Resolve the share argument: an existing path wins; otherwise a name (one
+// leading "/" stripped) searched across the four known locations.
+// Returns { matches: [{ root, isDir, type, agent, where }] }; throws CliError(2)
+// for no hit. Multiple hits are returned for the caller to pick or refuse.
+export async function resolveShareArg(arg, { cwd, home }) {
+  const asPath = path.resolve(cwd, arg);
+  if (existsSync(asPath)) {
+    const s = await stat(asPath);
+    const isDir = s.isDirectory();
+    const { type, agent } = classifyPath(asPath, isDir);
+    return { matches: [{ root: asPath, isDir, type, agent, where: 'explicit path' }] };
+  }
+  const name = arg.startsWith('/') ? arg.slice(1) : arg;
+  if (!name || name.includes('/')) {
+    throw new CliError(`No such path or skill: "${arg}"`, 2);
+  }
+  const matches = [];
+  for (const cand of nameCandidates(name, { cwd, home })) {
+    if (await existsAs(cand.root, cand.isDir)) {
+      matches.push({ ...cand, agent: 'claude-code' });
+    }
+  }
+  if (matches.length === 0) {
+    const known = await knownNames({ cwd, home });
+    const near = nearestNames(name, known);
+    let msg = `No skill named "${name}" found here or in ~/.claude.`;
+    if (near.length) msg += `\nDid you mean: ${near.join(', ')}?`;
+    else if (known.length) msg += `\nAvailable: ${known.slice(0, 8).join(', ')}`;
+    throw new CliError(msg, 2);
+  }
+  return { matches, name };
+}
+
+// --- file collection (§4.1 excludes) ----------------------------------------
+
+// Walk an artifact and apply the exclude rules. Returns:
+//   files:    [{ path, abs, size, mode, executable, sha256 }]
+//   warnings: [{ path, reason, forceable }]
+export async function collectFiles(root, { isDir, force = false } = {}) {
+  const files = [];
+  const warnings = [];
+
+  async function addFile(abs, rel) {
+    const data = await readFile(abs);
+    const s = await stat(abs);
+    const executable = Boolean(s.mode & 0o111);
+    files.push({
+      path: rel,
+      abs,
+      size: data.length,
+      mode: executable ? '0755' : '0644',
+      executable,
+      sha256: sha256hex(data),
+    });
+  }
+
+  async function consider(abs, rel, name) {
+    if (RESERVED_NAMES.has(name)) {
+      warnings.push({ path: rel, reason: 'reserved name', forceable: false });
+      return;
+    }
+    if (hardExcluded(name)) return; // silently never packaged
+    const secret = secretMatch(name);
+    if (secret && !force) {
+      warnings.push({ path: rel, reason: secret.label, forceable: true });
+      return;
+    }
+    await addFile(abs, rel);
+  }
+
+  if (!isDir) {
+    const name = path.basename(root);
+    await consider(root, name, name);
+  } else {
+    async function walk(dir, prefix) {
+      const dirents = (await readdir(dir, { withFileTypes: true }))
+        .sort((a, b) => (a.name < b.name ? -1 : 1));
+      for (const ent of dirents) {
+        const rel = prefix ? `${prefix}/${ent.name}` : ent.name;
+        const abs = path.join(dir, ent.name);
+        const ls = await lstat(abs);
+        if (ls.isSymbolicLink()) {
+          warnings.push({ path: rel, reason: 'symlink', forceable: false });
+          continue;
+        }
+        if (ent.isDirectory()) {
+          if (HARD_EXCLUDE_DIRS.has(ent.name)) continue;
+          await walk(abs, rel);
+        } else if (ent.isFile()) {
+          await consider(abs, rel, ent.name);
+        }
+      }
+    }
+    await walk(root, '');
+  }
+  files.sort((a, b) => (a.path < b.path ? -1 : 1));
+  return { files, warnings };
+}
+
+// --- metadata inference (§4.1) ----------------------------------------------
+
+// Tiny frontmatter reader: a leading "---" block of `key: value` lines.
+export function parseFrontmatter(text) {
+  const data = {};
+  if (!text.startsWith('---')) return { data, body: text };
+  const end = text.indexOf('\n---', 3);
+  if (end === -1) return { data, body: text };
+  const block = text.slice(text.indexOf('\n') + 1, end);
+  for (const line of block.split('\n')) {
+    const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!m) continue;
+    let value = m[2].trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    data[m[1]] = value;
+  }
+  return { data, body: text.slice(end + 4) };
+}
+
+function firstHeadingOrParagraph(body) {
+  const heading = body.match(/^#+\s+(.+)$/m);
+  if (heading) return heading[1].trim();
+  for (const block of body.split(/\n\s*\n/)) {
+    const t = block.trim();
+    if (t && !t.startsWith('#') && !t.startsWith('---')) return t.split('\n')[0].trim();
+  }
+  return '';
+}
+
+// The artifact's primary document: SKILL.md for a skill, the file itself for
+// single-file artifacts, else the only .md present.
+export function primaryDocPath(files, { isDir, type }) {
+  if (!isDir) return files[0]?.path ?? null;
+  const skillMd = files.find((f) => f.path === 'SKILL.md');
+  if (skillMd) return skillMd.path;
+  const mds = files.filter((f) => f.path.endsWith('.md') && !f.path.includes('/'));
+  if (mds.length === 1) return mds[0].path;
+  return null;
+}
+
+// name: frontmatter `name:` → basename (--name overrides, applied by caller).
+// description: frontmatter → first heading → first paragraph → "".
+export async function inferMetadata({ root, isDir, type, agent, files }) {
+  let fm = {};
+  let body = '';
+  const docRel = primaryDocPath(files, { isDir, type });
+  if (docRel) {
+    const docAbs = isDir ? path.join(root, ...docRel.split('/')) : root;
+    if (docAbs.endsWith('.md') || docRel.endsWith('.md')) {
+      try {
+        const text = await readFile(docAbs, 'utf8');
+        const parsed = parseFrontmatter(text);
+        fm = parsed.data;
+        body = parsed.body;
+      } catch { /* unreadable doc → fall back to basenames */ }
+    }
+  }
+  const base = path.basename(root).replace(/\.[^.]+$/, '');
+  const name = (fm.name && String(fm.name).trim()) || base;
+  const description = (fm.description && String(fm.description).trim()) || firstHeadingOrParagraph(body) || '';
+  const dependencies = [];
+  for (const key of ['requires', 'mcp']) {
+    if (fm[key]) dependencies.push({ [key]: fm[key] });
+  }
+  return { name, type, agent, description, dependencies, primaryDoc: docRel };
+}
+
+// §2.4 — relative references that escape the artifact ("../shared/util.md"):
+// the skill may not work standalone. Scans packaged .md files.
+export async function findExternalRefs(files) {
+  const refs = new Set();
+  for (const f of files) {
+    if (!f.path.endsWith('.md')) continue;
+    let text;
+    try {
+      text = await readFile(f.abs, 'utf8');
+    } catch {
+      continue;
+    }
+    for (const m of text.matchAll(/(?:^|[\s('"`(=])(\.\.\/[A-Za-z0-9_./-]+)/g)) {
+      refs.add(m[1]);
+    }
+  }
+  return [...refs].sort();
+}

package/src/errors.js

@@ -0,0 +1,21 @@
+// Exit codes (hard rule 6):
+//   0 — success or benign no-op
+//   1 — runtime/remote failure (expired, deleted, integrity, network)
+//   2 — usage/local error (bad args, not found, gh missing, too large)
+export class CliError extends Error {
+  constructor(message, exitCode = 1, details = undefined) {
+    super(message);
+    this.name = 'CliError';
+    this.exitCode = exitCode;
+    if (details !== undefined) this.details = details;
+  }
+}
+
+export const MSG = {
+  ghMissing:
+    'Sharing needs the GitHub CLI: https://cli.github.com, then "gh auth login". (Receivers don\'t need gh for public links.)',
+  gistDeleted: 'This share was deleted by the sender (gist not found).',
+  downloadIntegrity: 'Download failed integrity check. Did not install anything.',
+  linkIntegrity:
+    'Link integrity check failed — this share changed since the link was made, or the link was altered. Nothing was installed.',
+};

package/src/fingerprint.js

@@ -0,0 +1,29 @@
+import { createHash } from 'node:crypto';
+
+export function sha256hex(data) {
+  return createHash('sha256').update(data).digest('hex');
+}
+
+// §7.1 — tree fingerprint, independent of tar framing, mtimes, and file order.
+// entries = path + NUL + sha256hex, lexicographically byte-sorted, joined with "\n",
+// then sha256-hexed. skillshark.json itself is never part of `files`.
+export function treeFingerprint(files) {
+  const entries = files.map((f) => Buffer.from(f.path + '\u0000' + f.sha256, 'utf8'));
+  entries.sort(Buffer.compare);
+  const nl = Buffer.from('\n');
+  const parts = [];
+  for (let i = 0; i < entries.length; i++) {
+    if (i > 0) parts.push(nl);
+    parts.push(entries[i]);
+  }
+  return sha256hex(Buffer.concat(parts));
+}
+
+export function fp8(fingerprint) {
+  return fingerprint.slice(0, 8);
+}
+
+// fp8 displayed as XXXX-XXXX (e.g. 3f9a-7c21)
+export function formatFp8(fingerprint) {
+  return `${fingerprint.slice(0, 4)}-${fingerprint.slice(4, 8)}`;
+}

package/src/gh.js

@@ -0,0 +1,34 @@
+// The gh helper — the ONLY module (besides the clipboard) that touches
+// child_process. Used exclusively by sender operations (share, revoke).
+// Receivers never come through here. execFile with argument arrays only;
+// user input is never interpolated into a shell string (hard rule 3).
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import { CliError, MSG } from './errors.js';
+
+const execFileP = promisify(execFileCb);
+
+// Default runner; tests inject their own to capture or forbid calls.
+export async function defaultGhRunner(args) {
+  const { stdout } = await execFileP('gh', args, { maxBuffer: 32 * 1024 * 1024 });
+  return stdout;
+}
+
+// Run `gh api ...` and map the usual failure modes onto exit-code-2 guidance.
+export function makeGhApi(runner = defaultGhRunner) {
+  return async function ghApi(args) {
+    try {
+      return await runner(['api', ...args]);
+    } catch (err) {
+      if (err instanceof CliError) throw err;
+      if (err?.code === 'ENOENT') throw new CliError(MSG.ghMissing, 2);
+      const stderr = String(err?.stderr ?? '');
+      if (/not logged in|authentication|HTTP 401|gh auth login/i.test(stderr)) {
+        throw new CliError(MSG.ghMissing, 2);
+      }
+      if (/HTTP 404/.test(stderr)) throw new CliError('GitHub returned 404 for that id.', 1);
+      const detail = stderr.trim().split('\n')[0] || err.message;
+      throw new CliError(`gh failed: ${detail}`, 1);
+    }
+  };
+}