skillshark 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+# SkillShark 🦈
+
+**Share an agent skill like you'd share a file.** SkillShark packages a Claude Code skill (or command) into a secret GitHub gist and hands you an unlisted, self-verifying link; the receiver installs it with one command and zero setup — no GitHub account, no server, no registry.
+
+> ⚠️ **Secret gists are unlisted, NOT private — anyone with the link can read them.**
+> SkillShark scans for secret-shaped files (`.env`, keys, tokens) and refuses to package
+> them unless you `--force`. If you ever leak one anyway: `skillshark revoke` the share
+> *and rotate the secret* — gists keep revision history.
+
+## Install
+
+Zero-install:
+
+```sh
+npx skillshark install <link>
+```
+
+Or globally:
+
+```sh
+npm install -g skillshark
+```
+
+Requirements: Node ≥ 20. **Senders** also need the [GitHub CLI](https://cli.github.com) authenticated (`gh auth login`). **Receivers need nothing** — public links are fetched over plain anonymous HTTPS.
+
+## The four commands
+
+**share** — package a skill and get an unlisted link (auto-copied to your clipboard):
+
+```sh
+skillshark share /j
+# → https://gist.github.com/8a1bc94ef23d4b6a9c01e57f8d2a4b3c#fp=3f9a7c21
+```
+
+Accepts a name (`j`, `/j` — resolved across `./.claude/skills`, `./.claude/commands`, and their `~/` equivalents) or any path. Useful flags: `--expires 30m|6h|24h|7d|30d` (advisory, default 7d), `--dry-run`, `--name`, `--force`, `--no-clipboard`, `-q` (print only the URL).
+
+**install** — download, verify, preview, confirm, copy:
+
+```sh
+skillshark install https://gist.github.com/<id>#fp=<fp8>   # a SkillShark link
+skillshark install <gist-id>                               # bare id works too
+skillshark install gh:acme/skills/review@main              # any public repo path
+```
+
+Skills land in `.claude/skills/<name>/`, commands in `.claude/commands/<name>.md` (project scope when the cwd has `.claude/` or `.git`, else `--project`/`--global`/`--dir`). Useful flags: `--yes`, `--force`, `--allow-exec`, `--dir <path>`.
+
+**inspect** — look before you leap (writes nothing):
+
+```sh
+skillshark inspect <link> --cat SKILL.md
+```
+
+Inspect downloads and verifies the full package, so what you read is ground truth from checksummed bytes — never sender-declared metadata. The gist page itself is also a free browser preview (`SKILLSHARK.json` + `SKILL.md`).
+
+**revoke** — delete a share you created:
+
+```sh
+skillshark revoke j        # or the gist id
+```
+
+The gist dies immediately; anyone holding the link gets "deleted by the sender."
+(GitHub's anonymous API cache can serve a just-deleted gist for up to ~a minute
+before the 404 propagates everywhere.)
+
+## Security model
+
+- **SkillShark never executes package content.** Install = copy files. No postinstall hooks, no scripts, ever.
+- **Executable bits are stripped by default.** Executables are flagged in the preview; `--allow-exec` is required to keep them.
+- **Everything is verified.** Per-file sha256 checksums and a tree fingerprint are checked after extraction; path traversal, symlinks, absolute paths, decompression bombs, and oversized payloads all abort the install with nothing written.
+- **Links are self-verifying.** `share` appends `#fp=<fingerprint>` to the URL; `install` recomputes the fingerprint from the downloaded bytes and hard-fails on mismatch — if the gist was edited after sharing, you'll know.
+- **Receivers need no GitHub account.** The receive path uses anonymous HTTPS only and provably never invokes `gh` (enforced by tests).
+
+The honest framing: a skill is *instructions an AI will obey*. SkillShark is for sharing between people who already trust each other — it makes installs informed and tamper-evident, not safe-from-strangers. Read the preview.
+
+## Odds and ends
+
+- **Uninstall** = delete the directory (`rm -rf .claude/skills/<name>`). Install records live in `~/.config/skillshark/installs.json` (override the location with `$SKILLSHARK_CONFIG_DIR`).
+- **Expiry is advisory.** GitHub can't enforce TTLs: installers refuse past the expiry, but the bytes persist until you `revoke`.
+- **Too big for a gist (~5 MB)?** Put it in a repo and share `gh:owner/repo/path` instead.
+- Exit codes: `0` success/benign no-op · `1` runtime or remote failure · `2` usage error.
+
+## Development
+
+```sh
+npm test              # offline unit + integration suite (includes all security cases)
+npm run acceptance    # real-network end-to-end: share → install → tamper → revoke
+```

package/bin/skillshark.js

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+// Arg parsing + dispatch. Kept tiny: every behavior lives in src/.
+import process from 'node:process';
+import os from 'node:os';
+import { CliError } from '../src/errors.js';
+import { VERSION } from '../src/version.js';
+import { getConfigDir } from '../src/config.js';
+import { makeUi, realPrompts } from '../src/ui.js';
+import { makeGhApi } from '../src/gh.js';
+import { copyToClipboard } from '../src/clipboard.js';
+import { runShare, runRevoke } from '../src/share.js';
+import { runInstall, runInspect } from '../src/install.js';
+
+const HELP = `skillshark — share agent skills like files
+
+USAGE
+  skillshark <command> [options]
+
+COMMANDS
+  share    <path|name>   Package a skill and upload it as a secret gist
+  install  <source>      Download, verify, preview, and install a shared skill
+  inspect  <source>      Preview a shared skill without installing anything
+  revoke   <id|name>     Delete a share you created (deletes the gist)
+
+SOURCES (install / inspect)
+  https://gist.github.com/<id>#fp=<hex>    a SkillShark link
+  <gist id>                                bare 20-32 char hex id
+  gh:owner/repo[/path][@ref]               any public GitHub repo path
+
+GLOBAL OPTIONS
+  -y, --yes        Skip prompts (non-interactive)
+  -q, --quiet      Print only the essential result (URL or path)
+      --json       Machine-readable output
+      --no-color   Disable color (NO_COLOR is also honored)
+  -h, --help       Show help (try: skillshark help <command>)
+  -V, --version    Show version
+
+EXAMPLES
+  skillshark share /j                       share the "j" skill (secret gist)
+  skillshark install <gist-url|id>          install a shared skill
+  skillshark install gh:acme/skills/review  install straight from a repo path
+  skillshark inspect <gist-url> --cat SKILL.md
+  skillshark revoke j                       delete the share
+
+Secret gists are unlisted, NOT private — anyone with the link can read them.
+SkillShark never executes package content; install only copies files.`;
+
+const COMMAND_HELP = {
+  share: `skillshark share <path|name> — package a skill and get an unlisted link
+
+  -e, --expires <dur>   Advisory expiry: 30m | 6h | 24h | 7d | 30d (default 7d)
+      --name <name>     Override the inferred name
+      --force           Include secret-shaped files the scanner would skip
+      --no-clipboard    Don't copy the link to the clipboard
+      --dry-run         Show exactly what would be packaged; upload nothing
+  -q, --quiet           Print only the URL
+      --json            Print { id, url, revision, expiresAt, fingerprint, size, files }
+
+Sharing needs an authenticated gh (https://cli.github.com). The link is
+unlisted, not private: anyone holding it can read the gist. Undo with
+"skillshark revoke <name>".`,
+  install: `skillshark install <source> — download, verify, preview, confirm, copy
+
+  -y, --yes             Install without prompting (documented as dangerous)
+      --project         Install into ./.claude/... (default when cwd is a project)
+      --global          Install into ~/.claude/... (all projects)
+      --dir <path>      Install into an explicit directory (required for
+                        prompt/bundle packages; overrides agent detection)
+      --force           Overwrite an existing, differing artifact
+      --allow-exec      Keep executable bits (stripped by default)
+  -q, --quiet           Print only the installed path
+      --json            Print { name, type, agent, installedPath, ... }
+
+SkillShark never executes anything from a package. Integrity: per-file sha256
++ tree fingerprint, and the #fp= fragment in the link is enforced.`,
+  inspect: `skillshark inspect <source> — look before you leap (writes nothing)
+
+      --cat <path>      Print one file from the package
+      --files           File listing only
+      --json            Machine-readable summary
+
+Inspect downloads and verifies the full package, then shows you ground truth
+from checksummed bytes. Expired shares still display (only install refuses).`,
+  revoke: `skillshark revoke <id|name> — delete a share you created
+
+  -y, --yes             Skip the confirmation prompt
+      --json            Print { revoked: <id> }
+
+Deletes the underlying gist via your gh auth. The link dies immediately.`,
+};
+
+// flag spec: long name → { short, takesValue, key }
+const GLOBAL_FLAGS = {
+  yes: { short: 'y', key: 'yes' },
+  quiet: { short: 'q', key: 'quiet' },
+  json: { key: 'json' },
+  'no-color': { key: 'noColor' },
+  help: { short: 'h', key: 'help' },
+  version: { short: 'V', key: 'version' },
+};
+const COMMAND_FLAGS = {
+  share: {
+    expires: { short: 'e', takesValue: true, key: 'expires' },
+    name: { takesValue: true, key: 'name' },
+    force: { key: 'force' },
+    'no-clipboard': { key: 'noClipboard' },
+    'dry-run': { key: 'dryRun' },
+  },
+  install: {
+    project: { key: 'project' },
+    global: { key: 'global' },
+    force: { key: 'force' },
+    dir: { takesValue: true, key: 'dir' },
+    'allow-exec': { key: 'allowExec' },
+    agent: { takesValue: true, key: 'agent' },
+  },
+  inspect: {
+    cat: { takesValue: true, key: 'cat' },
+    files: { key: 'files' },
+  },
+  revoke: {},
+};
+
+function parseArgv(argv) {
+  const [first, ...rest] = argv;
+  if (!first || first === 'help') {
+    return { command: 'help', topic: rest[0] ?? null, opts: {}, positionals: [] };
+  }
+  if (first === '--help' || first === '-h') return { command: 'help', topic: null, opts: {}, positionals: [] };
+  if (first === '--version' || first === '-V') return { command: 'version', opts: {}, positionals: [] };
+  const command = first;
+  const flagDefs = { ...GLOBAL_FLAGS, ...(COMMAND_FLAGS[command] ?? {}) };
+  const shorts = {};
+  for (const [long, def] of Object.entries(flagDefs)) {
+    if (def.short) shorts[def.short] = long;
+  }
+  const opts = {};
+  const positionals = [];
+  for (let i = 0; i < rest.length; i++) {
+    const tok = rest[i];
+    if (tok === '--') {
+      positionals.push(...rest.slice(i + 1));
+      break;
+    }
+    let long = null;
+    if (tok.startsWith('--')) long = tok.slice(2);
+    else if (tok.startsWith('-') && tok.length === 2) long = shorts[tok[1]] ?? null;
+    else {
+      positionals.push(tok);
+      continue;
+    }
+    let inlineValue = null;
+    if (long && long.includes('=')) {
+      const eq = long.indexOf('=');
+      inlineValue = long.slice(eq + 1);
+      long = long.slice(0, eq);
+    }
+    const def = long ? flagDefs[long] : null;
+    if (!def) throw new CliError(`Unknown option "${tok}" for "${command}". Try: skillshark help ${command}`, 2);
+    if (def.takesValue) {
+      const value = inlineValue ?? rest[++i];
+      if (value === undefined) throw new CliError(`Option --${long} needs a value.`, 2);
+      opts[def.key] = value;
+    } else {
+      opts[def.key] = true;
+    }
+  }
+  return { command, opts, positionals };
+}
+
+async function main() {
+  const parsed = parseArgv(process.argv.slice(2));
+  const isTTY = Boolean(process.stdout.isTTY && process.stdin.isTTY);
+  const color = parsed.opts.noColor || process.env.NO_COLOR ? false : undefined;
+  const ui = makeUi({ color });
+
+  if (parsed.command === 'help') {
+    if (parsed.topic && COMMAND_HELP[parsed.topic]) ui.out(COMMAND_HELP[parsed.topic]);
+    else ui.out(HELP);
+    return 0;
+  }
+  if (parsed.command === 'version') {
+    ui.out(VERSION);
+    return 0;
+  }
+  if (parsed.opts.help) {
+    ui.out(COMMAND_HELP[parsed.command] ?? HELP);
+    return 0;
+  }
+  if (parsed.opts.version) {
+    ui.out(VERSION);
+    return 0;
+  }
+
+  const known = new Set(['share', 'install', 'inspect', 'revoke']);
+  if (!known.has(parsed.command)) {
+    throw new CliError(`Unknown command "${parsed.command}". Commands: share, install, inspect, revoke. Try: skillshark --help`, 2);
+  }
+  if (parsed.opts.agent && parsed.opts.agent !== 'claude-code') {
+    throw new CliError(`Only --agent claude-code is supported in v0.1 (got "${parsed.opts.agent}").`, 2);
+  }
+
+  const arg = parsed.positionals[0];
+  if (!arg) {
+    const noun = parsed.command === 'share' ? '<path|name>' : parsed.command === 'revoke' ? '<id|name>' : '<source>';
+    throw new CliError(`Usage: skillshark ${parsed.command} ${noun}. Try: skillshark help ${parsed.command}`, 2);
+  }
+  if (parsed.positionals.length > 1) {
+    throw new CliError(`Too many arguments: ${parsed.positionals.slice(1).join(' ')}`, 2);
+  }
+
+  // --json is non-interactive by definition (§1.9)
+  const effectiveTTY = parsed.opts.json ? false : isTTY;
+  const deps = {
+    fetch: globalThis.fetch,
+    cwd: process.cwd(),
+    home: os.homedir(),
+    env: process.env,
+    isTTY: effectiveTTY,
+    configDir: getConfigDir(process.env),
+    ui,
+    prompts: effectiveTTY ? await realPrompts() : null,
+    ghApi: makeGhApi(),
+    clipboard: (text) => copyToClipboard(text),
+  };
+
+  switch (parsed.command) {
+    case 'share':
+      await runShare(arg, parsed.opts, deps);
+      return 0;
+    case 'install':
+      await runInstall(arg, parsed.opts, deps);
+      return 0;
+    case 'inspect':
+      await runInspect(arg, parsed.opts, deps);
+      return 0;
+    case 'revoke':
+      await runRevoke(arg, parsed.opts, deps);
+      return 0;
+    default:
+      return 2;
+  }
+}
+
+try {
+  const code = await main();
+  process.exit(code);
+} catch (err) {
+  if (err instanceof CliError) {
+    const stream = err.exitCode === 0 ? process.stdout : process.stderr;
+    stream.write(`${err.exitCode === 0 ? '' : '✗ '}${err.message}\n`);
+    process.exit(err.exitCode);
+  }
+  process.stderr.write(`Unexpected error: ${err?.stack ?? err}\n`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "skillshark",
+  "version": "0.1.0",
+  "description": "Share agent skills like files — secret gists out, safe verified installs in. No server; GitHub is the backend.",
+  "type": "module",
+  "bin": {
+    "skillshark": "./bin/skillshark.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "claude-code",
+    "agent-skills",
+    "skills",
+    "gist",
+    "cli",
+    "sharing"
+  ],
+  "author": "Aaron Turkel",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test 'test/**/*.test.js'",
+    "acceptance": "bash scripts/acceptance.sh"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "picocolors": "^1.1.1",
+    "tar": "^7.4.3"
+  },
+  "license": "MIT"
+}

package/src/clipboard.js

@@ -0,0 +1,45 @@
+// Clipboard helper — the second of exactly two modules allowed to touch
+// child_process. Best effort, never blocks longer than ~500 ms, never fails
+// the share: pbcopy → wl-copy → xclip → clip.exe → OSC52 → shrug.
+import { execFile } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+
+const TIMEOUT_MS = 500;
+
+function tryPipe(cmd, args, text) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = execFile(cmd, args, { timeout: TIMEOUT_MS }, (err) => resolve(!err));
+    } catch {
+      resolve(false);
+      return;
+    }
+    child.on('error', () => resolve(false));
+    if (child.stdin) {
+      child.stdin.on('error', () => {});
+      child.stdin.end(text);
+    }
+  });
+}
+
+function tryOsc52(text) {
+  try {
+    // works over SSH when the terminal supports it; harmless otherwise
+    writeFileSync('/dev/tty', `\x1b]52;c;${Buffer.from(text).toString('base64')}\x07`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function copyToClipboard(text, { platform = process.platform } = {}) {
+  const candidates =
+    platform === 'darwin'
+      ? [['pbcopy', []]]
+      : [['wl-copy', []], ['xclip', ['-selection', 'clipboard']], ['clip.exe', []]];
+  for (const [cmd, args] of candidates) {
+    if (await tryPipe(cmd, args, text)) return true;
+  }
+  return tryOsc52(text);
+}

package/src/config.js

@@ -0,0 +1,62 @@
+// Client-side state: ~/.config/skillshark/ (or $SKILLSHARK_CONFIG_DIR).
+// config.json — shares cache so `revoke <name>` resolves offline.
+// installs.json — local install records (client-side by design).
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+export function getConfigDir(env = process.env) {
+  return env.SKILLSHARK_CONFIG_DIR || path.join(os.homedir(), '.config', 'skillshark');
+}
+
+async function readJson(file, fallback) {
+  try {
+    return JSON.parse(await readFile(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+async function writeJson(file, value) {
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, JSON.stringify(value, null, 2) + '\n');
+}
+
+export async function loadConfig(dir) {
+  const cfg = await readJson(path.join(dir, 'config.json'), {});
+  if (!Array.isArray(cfg.shares)) cfg.shares = [];
+  return cfg;
+}
+
+export async function saveConfig(dir, cfg) {
+  await writeJson(path.join(dir, 'config.json'), cfg);
+}
+
+export async function addShareRecord(dir, record) {
+  const cfg = await loadConfig(dir);
+  cfg.shares.unshift(record);
+  await saveConfig(dir, cfg);
+}
+
+export async function findShareRecord(dir, idOrName) {
+  const cfg = await loadConfig(dir);
+  return cfg.shares.find((s) => s.id === idOrName) ?? cfg.shares.find((s) => s.name === idOrName) ?? null;
+}
+
+export async function removeShareRecord(dir, id) {
+  const cfg = await loadConfig(dir);
+  cfg.shares = cfg.shares.filter((s) => s.id !== id);
+  await saveConfig(dir, cfg);
+}
+
+export async function loadInstalls(dir) {
+  const v = await readJson(path.join(dir, 'installs.json'), []);
+  return Array.isArray(v) ? v : [];
+}
+
+export async function addInstallRecord(dir, record) {
+  const installs = await loadInstalls(dir);
+  const next = installs.filter((r) => r.path !== record.path);
+  next.unshift(record);
+  await writeJson(path.join(dir, 'installs.json'), next);
+}