skillshark 0.1.0

package/src/pkg.js

@@ -0,0 +1,260 @@
+// The security core: build, extract, verify. SkillShark never executes
+// package content — extraction writes regular files and directories, nothing else.
+import { mkdtemp, mkdir, writeFile, readFile, readdir, chmod, rm, stat } from 'node:fs/promises';
+import { createGunzip } from 'node:zlib';
+import path from 'node:path';
+import os from 'node:os';
+import * as tar from 'tar';
+import { sha256hex, treeFingerprint } from './fingerprint.js';
+import { CliError, MSG } from './errors.js';
+
+export const MAX_DECOMPRESSED_BYTES = 50 * 1024 * 1024;
+export const MAX_FILES = 500;
+export const MANIFEST_NAME = 'skillshark.json';
+
+export class ExtractError extends CliError {
+  constructor(message, details) {
+    super(message, 1, details);
+    this.name = 'ExtractError';
+  }
+}
+
+// --- build ----------------------------------------------------------------
+
+// files: [{ path, abs, executable }] — path is "/"-separated, relative to package root.
+// Returns the canonical tarball with `skillshark.json` at the archive root.
+export async function buildTarball(files, manifest) {
+  const staging = await mkdtemp(path.join(os.tmpdir(), 'skillshark-pack-'));
+  try {
+    for (const f of files) {
+      const dest = path.join(staging, ...f.path.split('/'));
+      await mkdir(path.dirname(dest), { recursive: true });
+      await writeFile(dest, await readFile(f.abs));
+      await chmod(dest, f.executable ? 0o755 : 0o644);
+    }
+    const manifestJson = JSON.stringify(manifest, null, 2) + '\n';
+    await writeFile(path.join(staging, MANIFEST_NAME), manifestJson);
+    const tarFile = path.join(staging, '..', `skillshark-tar-${process.pid}-${Date.now()}.tgz`);
+    try {
+      await tar.create(
+        { file: tarFile, gzip: true, cwd: staging, portable: true },
+        [MANIFEST_NAME, ...files.map((f) => f.path)],
+      );
+      return { tarball: await readFile(tarFile), manifestJson };
+    } finally {
+      await rm(tarFile, { force: true });
+    }
+  } finally {
+    await rm(staging, { recursive: true, force: true });
+  }
+}
+
+// --- extract ---------------------------------------------------------------
+
+// Reject anything that could land outside the extraction root. Returns the
+// cleaned, "/"-joined relative path ('' for the root itself).
+function cleanEntryPath(raw) {
+  let p = String(raw);
+  if (p.includes('\u0000')) throw new ExtractError('Refused tar entry: NUL byte in path.');
+  if (p.includes('\\')) throw new ExtractError(`Refused tar entry "${p}": backslash in path.`);
+  if (/^[A-Za-z]:/.test(p)) throw new ExtractError(`Refused tar entry "${p}": drive letter path.`);
+  if (p.startsWith('/')) throw new ExtractError(`Refused tar entry "${p}": absolute path.`);
+  const segs = p.split('/').filter((s) => s !== '' && s !== '.');
+  if (segs.includes('..')) throw new ExtractError(`Refused tar entry "${p}": path traversal ("..").`);
+  return segs.join('/');
+}
+
+// Guarded streaming extraction (§7.2). Own entry filter — node-tar's built-in
+// protections are not relied on. transformPath(cleanPath) → string|null lets the
+// repo transport strip the codeload prefix and select a subtree; null skips.
+export async function extractTarball(tarball, destRoot, opts = {}) {
+  const {
+    maxBytes = MAX_DECOMPRESSED_BYTES,
+    maxFiles = MAX_FILES,
+    transformPath = null,
+  } = opts;
+
+  const root = path.resolve(destRoot);
+  const entries = [];
+  let bytesSeen = 0;
+  let fileCount = 0;
+  let openEntries = 0;
+
+  await new Promise((resolve, reject) => {
+    let settled = false;
+    const gunzip = createGunzip();
+    const parser = new tar.Parser();
+    const fail = (err) => {
+      if (settled) return;
+      settled = true;
+      try { gunzip.destroy(); } catch { /* already dead */ }
+      try { parser.abort(err); } catch { /* best effort */ }
+      reject(err);
+    };
+    const done = () => {
+      if (settled) return;
+      if (openEntries > 0) {
+        fail(new ExtractError('Truncated archive: a file entry ended early. Nothing was installed.'));
+        return;
+      }
+      settled = true;
+      resolve();
+    };
+
+    parser.on('entry', (entry) => {
+      try {
+        if (entry.meta) { entry.resume(); return; } // pax/gnu metadata consumed by the parser
+        const cleaned = cleanEntryPath(entry.path);
+        const mapped = transformPath ? transformPath(cleaned, entry.type) : cleaned;
+        if (mapped === null || mapped === undefined || mapped === '') {
+          if (entry.type === 'File' && !transformPath && mapped === '') {
+            throw new ExtractError(`Refused tar entry "${entry.path}": empty path.`);
+          }
+          entry.resume();
+          return;
+        }
+        const rel = cleanEntryPath(mapped); // re-validate after any transform
+        const resolved = path.resolve(root, ...rel.split('/'));
+        if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+          throw new ExtractError(`Refused tar entry "${entry.path}": escapes extraction root.`);
+        }
+        if (entry.type === 'Directory') {
+          entries.push({ rel, type: 'dir' });
+          entry.resume();
+          return;
+        }
+        if (entry.type !== 'File') {
+          throw new ExtractError(
+            `Refused tar entry "${entry.path}": type "${entry.type}" is not allowed (only files and directories).`,
+          );
+        }
+        fileCount += 1;
+        if (fileCount > maxFiles) {
+          throw new ExtractError(`Package has too many files (limit ${maxFiles}). Nothing was installed.`);
+        }
+        openEntries += 1;
+        const expected = entry.size ?? 0;
+        const chunks = [];
+        entry.on('data', (c) => chunks.push(c));
+        entry.on('end', () => {
+          const data = Buffer.concat(chunks);
+          if (data.length !== expected) {
+            fail(new ExtractError(`Truncated archive: "${rel}" ended early. Nothing was installed.`));
+            return;
+          }
+          openEntries -= 1;
+          entries.push({ rel, type: 'file', mode: entry.mode ?? 0o644, data });
+        });
+      } catch (err) {
+        fail(err);
+      }
+    });
+    parser.on('error', fail);
+    // strict mode: a malformed entry the parser would skip (bad checksum,
+    // forbidden linkpath, unsupported extension) aborts the whole extraction
+    parser.on('warn', (code, message) => {
+      fail(new ExtractError(`Refused malformed archive entry (${code}: ${message}). Nothing was installed.`));
+    });
+    parser.on('end', done);
+    parser.on('close', done);
+
+    gunzip.on('data', (chunk) => {
+      bytesSeen += chunk.length;
+      if (bytesSeen > maxBytes) {
+        fail(new ExtractError(
+          `Package expands past the ${Math.floor(maxBytes / (1024 * 1024))} MB safety limit. Nothing was installed.`,
+          { bytesSeen },
+        ));
+        return;
+      }
+      parser.write(chunk);
+    });
+    gunzip.on('end', () => parser.end());
+    gunzip.on('error', (e) => fail(new ExtractError(`Not a valid package (gzip): ${e.message}`)));
+    gunzip.end(tarball);
+  });
+
+  for (const e of entries) {
+    const dest = path.resolve(root, ...e.rel.split('/'));
+    if (e.type === 'dir') {
+      await mkdir(dest, { recursive: true });
+    } else {
+      await mkdir(path.dirname(dest), { recursive: true });
+      await writeFile(dest, e.data, { mode: (e.mode & 0o111) ? 0o755 : 0o644 });
+    }
+  }
+  return { bytesSeen, fileCount };
+}
+
+// --- verify ----------------------------------------------------------------
+
+// Walk an on-disk tree → [{ path, size, sha256, executable }], sorted by path.
+// Symlinks and special files are never followed or hashed.
+export async function hashTree(dir, { exclude = [MANIFEST_NAME] } = {}) {
+  const out = [];
+  async function walk(d, prefix) {
+    const dirents = await readdir(d, { withFileTypes: true });
+    for (const ent of dirents) {
+      const rel = prefix ? `${prefix}/${ent.name}` : ent.name;
+      if (!prefix && exclude.includes(ent.name)) continue;
+      if (ent.isDirectory()) await walk(path.join(d, ent.name), rel);
+      else if (ent.isFile()) {
+        const abs = path.join(d, ent.name);
+        const data = await readFile(abs);
+        const { mode } = await stat(abs);
+        out.push({
+          path: rel,
+          size: data.length,
+          sha256: sha256hex(data),
+          executable: Boolean(mode & 0o111),
+        });
+      }
+      // anything else (symlink smuggled in, fifo, …) is ignored: we never wrote it
+    }
+  }
+  await walk(dir, '');
+  out.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return out;
+}
+
+export async function readManifest(dir) {
+  let raw;
+  try {
+    raw = await readFile(path.join(dir, MANIFEST_NAME), 'utf8');
+  } catch {
+    throw new CliError('No package at that link (missing skillshark.json — not a SkillShark share).', 1);
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(raw);
+  } catch {
+    throw new CliError(MSG.downloadIntegrity, 1);
+  }
+  if (!manifest || !Array.isArray(manifest.files) || typeof manifest.name !== 'string') {
+    throw new CliError(MSG.downloadIntegrity, 1);
+  }
+  return manifest;
+}
+
+// Per-file sha256 + exact set equality between the manifest and the extracted
+// tree. Returns the tree fingerprint computed from the *actual* bytes.
+export function verifyTreeAgainstManifest(actualFiles, manifest) {
+  const actualByPath = new Map(actualFiles.map((f) => [f.path, f]));
+  const manifestByPath = new Map();
+  for (const f of manifest.files) {
+    if (typeof f.path !== 'string' || typeof f.sha256 !== 'string') {
+      throw new CliError(MSG.downloadIntegrity, 1);
+    }
+    manifestByPath.set(f.path, f);
+  }
+  if (actualByPath.size !== manifestByPath.size) throw new CliError(MSG.downloadIntegrity, 1);
+  for (const [p, mf] of manifestByPath) {
+    const af = actualByPath.get(p);
+    if (!af || af.sha256 !== mf.sha256) throw new CliError(MSG.downloadIntegrity, 1);
+  }
+  const fingerprint = treeFingerprint(actualFiles);
+  if (manifest.fingerprint && manifest.fingerprint !== fingerprint) {
+    throw new CliError(MSG.downloadIntegrity, 1);
+  }
+  return fingerprint;
+}

package/src/share.js

@@ -0,0 +1,249 @@
+// `skillshark share <path|name>` (§4.1) and `skillshark revoke <id|name>` (§4.4).
+// Sender operations are the only ones that use gh; they never run package content.
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { CliError } from './errors.js';
+import { resolveShareArg, collectFiles, inferMetadata, findExternalRefs } from './discover.js';
+import { buildTarball } from './pkg.js';
+import { treeFingerprint, fp8 } from './fingerprint.js';
+import { createGist, deleteGist, gistDescription, GIST_PAYLOAD_LIMIT } from './transports/gist.js';
+import { addShareRecord, findShareRecord, removeShareRecord } from './config.js';
+import { humanSize, displayPath, plural } from './ui.js';
+import { VERSION } from './version.js';
+
+const EXPIRES = {
+  '30m': 30 * 60 * 1000,
+  '6h': 6 * 3600 * 1000,
+  '24h': 24 * 3600 * 1000,
+  '7d': 7 * 86400000,
+  '30d': 30 * 86400000,
+};
+const EXPIRES_LABEL = {
+  '30m': '30 minutes',
+  '6h': '6 hours',
+  '24h': '24 hours',
+  '7d': '7 days',
+  '30d': '30 days',
+};
+
+export function parseExpires(value) {
+  const v = value ?? '7d';
+  if (!Object.hasOwn(EXPIRES, v)) {
+    throw new CliError(`--expires must be one of: 30m, 6h, 24h, 7d, 30d (got "${value}").`, 2);
+  }
+  return { ms: EXPIRES[v], label: EXPIRES_LABEL[v], key: v };
+}
+
+// Assemble everything `share` needs before any upload happens. Also used by
+// --dry-run. Returns { files, warnings, manifest, manifestJson, tarball, fp }.
+export async function buildSharePackage(arg, opts, deps) {
+  const { matches } = await resolveShareArg(arg, deps);
+  let match;
+  if (matches.length === 1) {
+    [match] = matches;
+  } else if (deps.isTTY && deps.prompts) {
+    const value = await deps.prompts.select({
+      message: `"${arg}" matches more than one artifact:`,
+      options: matches.map((m, i) => ({ value: i, label: `${m.type} at ${displayPath(m.root, deps)}`, hint: m.where })),
+    });
+    if (value === null) throw new CliError('Cancelled.', 0);
+    match = matches[value];
+  } else {
+    throw new CliError(
+      `"${arg}" is ambiguous here:\n${matches.map((m) => `  ${m.type}  ${displayPath(m.root, deps)}`).join('\n')}\nPass the path you mean.`,
+      2,
+    );
+  }
+
+  const { files, warnings } = await collectFiles(match.root, { isDir: match.isDir, force: opts.force });
+  if (files.length === 0) {
+    throw new CliError(
+      'Nothing to package: every file was excluded (or the directory is empty). Use --force to include secret-shaped files you really mean to share.',
+      2,
+    );
+  }
+  const meta = await inferMetadata({
+    root: match.root,
+    isDir: match.isDir,
+    type: match.type,
+    agent: match.agent,
+    files,
+  });
+  const name = opts.name || meta.name;
+  const expires = parseExpires(opts.expires);
+  const now = Date.now();
+  const fingerprint = treeFingerprint(files);
+  const manifest = {
+    skillshark: '2',
+    name,
+    type: match.type,
+    agent: match.agent,
+    description: meta.description,
+    files: files.map(({ path: p, size, sha256, mode, executable }) => ({ path: p, size, sha256, mode, executable })),
+    totalSize: files.reduce((n, f) => n + f.size, 0),
+    createdAt: new Date(now).toISOString(),
+    expiresAt: new Date(now + expires.ms).toISOString(),
+    tool: { name: 'skillshark', version: VERSION },
+    dependencies: meta.dependencies,
+    fingerprint,
+  };
+  const externalRefs = await findExternalRefs(files);
+  const { tarball, manifestJson } = await buildTarball(
+    files.map((f) => ({ path: f.path, abs: f.abs, executable: f.executable })),
+    manifest,
+  );
+  return { match, files, warnings, manifest, manifestJson, tarball, fingerprint, expires, externalRefs, meta };
+}
+
+export async function runShare(arg, opts, deps) {
+  const ui = deps.ui;
+  const built = await buildSharePackage(arg, opts, deps);
+  const { match, files, warnings, manifest, manifestJson, tarball, fingerprint, expires, externalRefs } = built;
+  const shortFp = fp8(fingerprint);
+  const loud = !opts.quiet && !opts.json;
+
+  if (loud) {
+    const kind = manifest.agent ? `${manifest.type} "${manifest.name}" (${manifest.agent})` : `${manifest.type} "${manifest.name}"`;
+    ui.out(`  Found ${kind} at ${displayPath(match.root, deps)} — ${plural(files.length, 'file')}, ${humanSize(manifest.totalSize)}`);
+    for (const w of warnings) {
+      if (w.forceable) ui.warn(`Skipped ${w.path} (${w.reason}) — pass --force to include`);
+      else ui.warn(`Skipped ${w.path} (${w.reason})`);
+    }
+    for (const ref of externalRefs) {
+      ui.warn(`References ${ref} outside the package — it may not work standalone`);
+    }
+  }
+
+  const b64 = tarball.toString('base64');
+  if (b64.length > GIST_PAYLOAD_LIMIT) {
+    throw new CliError(
+      `That's ${humanSize(b64.length)} (gist limit ~5 MB). Put it in a repo and share gh:owner/repo/path instead.`,
+      2,
+    );
+  }
+
+  if (opts.dryRun) {
+    if (opts.json) {
+      ui.out(JSON.stringify({
+        dryRun: true,
+        name: manifest.name,
+        type: manifest.type,
+        agent: manifest.agent,
+        fingerprint,
+        size: manifest.totalSize,
+        encodedSize: b64.length,
+        files: manifest.files,
+      }, null, 2));
+    } else {
+      ui.out('');
+      for (const f of manifest.files) {
+        ui.out(`    ${f.path.padEnd(Math.max(...manifest.files.map((x) => x.path.length)) + 3)}${humanSize(f.size)}${f.executable ? '   (executable)' : ''}`);
+      }
+      ui.out('');
+      ui.out(`  Fingerprint ${shortFp} · ${humanSize(b64.length)} encoded · nothing uploaded (--dry-run)`);
+    }
+    return { status: 'dry-run', fingerprint };
+  }
+
+  let primaryDoc = null;
+  if (built.meta.primaryDoc) {
+    const abs = match.isDir ? path.join(match.root, ...built.meta.primaryDoc.split('/')) : match.root;
+    try {
+      primaryDoc = { name: built.meta.primaryDoc, content: await readFile(abs, 'utf8') };
+    } catch { /* preview is optional */ }
+  }
+
+  const { id, revision } = await createGist({
+    manifestJson,
+    primaryDoc,
+    tarballB64: b64,
+    description: gistDescription({ name: manifest.name, agent: manifest.agent, type: manifest.type, fp8: shortFp }),
+    ghApi: deps.ghApi,
+  });
+  const url = `https://gist.github.com/${id}#fp=${shortFp}`;
+
+  await addShareRecord(deps.configDir, {
+    id,
+    name: manifest.name,
+    url,
+    revision,
+    expiresAt: manifest.expiresAt,
+  });
+
+  let copied = false;
+  if (!opts.noClipboard && deps.clipboard) {
+    copied = await deps.clipboard(url);
+  }
+
+  if (opts.json) {
+    ui.out(JSON.stringify({
+      id,
+      url,
+      revision,
+      expiresAt: manifest.expiresAt,
+      fingerprint,
+      size: manifest.totalSize,
+      files: manifest.files.map((f) => f.path),
+    }));
+  } else if (opts.quiet) {
+    ui.out(url);
+  } else {
+    ui.out('');
+    ui.ok('Uploaded as a secret gist (unlisted — anyone with the link can read it)');
+    if (copied) ui.ok(`Link copied to clipboard · advisory expiry in ${expires.label}`);
+    else ui.out(`  Advisory expiry in ${expires.label}`);
+    ui.out('');
+    ui.out(`  ${url}`);
+    ui.out('');
+    ui.out('  They run:   skillshark install <the link>     (no GitHub account needed)');
+    ui.out(`  Undo:       skillshark revoke ${manifest.name}               (deletes the gist)`);
+  }
+  return { status: 'shared', id, url, fingerprint };
+}
+
+// --- revoke (§4.4) -----------------------------------------------------------
+
+export async function runRevoke(idOrName, opts, deps) {
+  const ui = deps.ui;
+  let id = null;
+  let label = idOrName;
+  if (/^[0-9a-f]{20,32}$/.test(idOrName)) {
+    id = idOrName;
+  } else {
+    const rec = await findShareRecord(deps.configDir, idOrName);
+    if (rec) {
+      id = rec.id;
+      label = `${rec.name} (${rec.id})`;
+    } else {
+      // cache miss → ask gh for our skillshark gists
+      const out = await deps.ghApi(['gists', '--paginate']);
+      let gists;
+      try {
+        gists = JSON.parse(out);
+      } catch {
+        throw new CliError('Unexpected response from gh while listing gists.', 1);
+      }
+      const mine = gists.filter((g) => (g.description ?? '').startsWith(`skillshark: ${idOrName} (`));
+      if (mine.length === 0) {
+        throw new CliError(`No share named "${idOrName}" found (locally or in your gists).`, 2);
+      }
+      mine.sort((a, b) => String(b.created_at).localeCompare(String(a.created_at)));
+      id = mine[0].id;
+      label = `${idOrName} (${id})`;
+      if (mine.length > 1) ui.warn(`${mine.length} shares named "${idOrName}" exist; revoking the newest. Re-run with the gist id for the others.`);
+    }
+  }
+
+  if (deps.isTTY && !opts.yes) {
+    const go = await deps.prompts.confirm({ message: `Delete the gist for ${label}? Anyone holding the link loses access.` });
+    if (go !== true) {
+      ui.out('  Cancelled.');
+      return { status: 'cancelled' };
+    }
+  }
+  await deleteGist(id, { ghApi: deps.ghApi });
+  await removeShareRecord(deps.configDir, id);
+  if (opts.json) ui.out(JSON.stringify({ revoked: id }));
+  else ui.ok(`Revoked — the gist ${id} is gone. Anyone holding the link now gets "deleted by the sender".`);
+  return { status: 'revoked', id };
+}

package/src/source.js

@@ -0,0 +1,58 @@
+// §7.3 — source parsing. Accepted forms:
+//   https://gist.github.com/<id>            (optionally <user>/<id>, optionally #fp=<hex>)
+//   <20-32 char hex gist id>
+//   gh:owner/repo[/deep/path][@ref]         (ref = branch, tag, or SHA; split on the LAST "@")
+import { CliError } from './errors.js';
+
+const USAGE = `Unrecognized source. Accepted forms:
+  https://gist.github.com/8a1bc94ef23d4b6a9c01e57f8d2a4b3c#fp=3f9a7c21
+  8a1bc94ef23d4b6a9c01e57f8d2a4b3c
+  gh:owner/repo[/deep/path][@ref]`;
+
+const NAME_RE = /^[A-Za-z0-9_.-]+$/;
+
+export function parseSource(input) {
+  const s = String(input ?? '').trim();
+  if (!s) throw new CliError(USAGE, 2);
+
+  const gistUrl = s.match(
+    /^https:\/\/gist\.github\.com\/(?:([A-Za-z0-9-]+)\/)?([0-9a-f]{20,32})\/?(?:#fp=([0-9a-f]{8,64}))?$/,
+  );
+  if (gistUrl) {
+    return { kind: 'gist', id: gistUrl[2], fp: gistUrl[3] ?? null };
+  }
+
+  if (/^[0-9a-f]{20,32}$/.test(s)) {
+    return { kind: 'gist', id: s, fp: null };
+  }
+
+  if (s.startsWith('gh:')) {
+    let rest = s.slice(3);
+    let ref = null;
+    const at = rest.lastIndexOf('@');
+    if (at !== -1) {
+      ref = rest.slice(at + 1);
+      rest = rest.slice(0, at);
+      if (!ref) throw new CliError(USAGE, 2);
+    }
+    const segs = rest.split('/').filter(Boolean);
+    if (segs.length >= 2 && NAME_RE.test(segs[0]) && NAME_RE.test(segs[1])) {
+      return {
+        kind: 'repo',
+        owner: segs[0],
+        repo: segs[1],
+        path: segs.length > 2 ? segs.slice(2).join('/') : null,
+        ref,
+      };
+    }
+  }
+
+  throw new CliError(`Unrecognized source: "${s}"\n${USAGE.split('\n').slice(1).join('\n')}`, 2);
+}
+
+export function formatSource(src) {
+  if (src.kind === 'gist') return `gist:${src.id}`;
+  const p = src.path ? `/${src.path}` : '';
+  const r = src.ref ? `@${src.ref}` : '';
+  return `gh:${src.owner}/${src.repo}${p}${r}`;
+}

package/src/transports/gist.js

@@ -0,0 +1,117 @@
+// Gist transport. Share/revoke go through `gh` (the sender's auth); the
+// receive path is ANONYMOUS https only — it must never invoke gh (§0.3).
+import { mkdtemp, writeFile, rm } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { CliError, MSG } from '../errors.js';
+import { USER_AGENT } from '../version.js';
+
+export const GIST_PAYLOAD_LIMIT = 5 * 1024 * 1024; // encoded bytes (§4.1)
+const FETCH_HEADERS = {
+  Accept: 'application/vnd.github+json',
+  'User-Agent': USER_AGENT,
+  'X-GitHub-Api-Version': '2022-11-28',
+  // anonymous API responses are CDN-cached; a revoked gist must die promptly
+  'Cache-Control': 'no-cache',
+};
+
+// --- sender side (gh) -------------------------------------------------------
+
+export function gistDescription({ name, agent, type, fp8 }) {
+  const kind = agent ? `${agent} ${type}` : type;
+  return `skillshark: ${name} (${kind}) · fp ${fp8}`;
+}
+
+// One `gh api gists --method POST --input <tmp.json>` call; a JSON body file
+// avoids every shell-escaping pitfall (hard rule 3).
+export async function createGist({ manifestJson, primaryDoc, tarballB64, description, ghApi }) {
+  const files = { 'SKILLSHARK.json': { content: manifestJson } };
+  if (primaryDoc && primaryDoc.content.trim()) {
+    files[path.basename(primaryDoc.name)] = { content: primaryDoc.content };
+  }
+  files['package.tgz.b64'] = { content: tarballB64 };
+  const body = { public: false, description, files };
+
+  const tmpDir = await mkdtemp(path.join(os.tmpdir(), 'skillshark-share-'));
+  const bodyFile = path.join(tmpDir, 'gist-body.json');
+  try {
+    await writeFile(bodyFile, JSON.stringify(body));
+    const stdout = await ghApi(['gists', '--method', 'POST', '--input', bodyFile]);
+    let parsed;
+    try {
+      parsed = JSON.parse(stdout);
+    } catch {
+      throw new CliError('Unexpected response from gh while creating the gist.', 1);
+    }
+    if (!parsed.id) throw new CliError('gh created no gist (no id in response).', 1);
+    return { id: parsed.id, revision: parsed.history?.[0]?.version ?? null };
+  } finally {
+    await rm(tmpDir, { recursive: true, force: true });
+  }
+}
+
+export async function deleteGist(id, { ghApi }) {
+  await ghApi(['--method', 'DELETE', `gists/${id}`]);
+}
+
+// --- receive side (anonymous fetch, no gh — ever) ---------------------------
+
+async function readBodyCapped(res, cap, what) {
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of res.body) {
+    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    total += buf.length;
+    if (total > cap) {
+      throw new CliError(`${what} exceeds the ${Math.floor(cap / (1024 * 1024))} MB limit. Refusing to continue.`, 1);
+    }
+    chunks.push(buf);
+  }
+  return Buffer.concat(chunks);
+}
+
+export async function fetchGistPackage(id, { fetch }) {
+  let res;
+  try {
+    res = await fetch(`https://api.github.com/gists/${id}`, { headers: FETCH_HEADERS });
+  } catch (e) {
+    throw new CliError(`Network error reaching GitHub: ${e.message}`, 1);
+  }
+  if (res.status === 404) throw new CliError(MSG.gistDeleted, 1);
+  if (res.status === 403 || res.status === 429) {
+    throw new CliError('GitHub rate limit hit (anonymous reads are 60/hour per IP). Try again in a bit.', 1);
+  }
+  if (!res.ok) throw new CliError(`GitHub API error fetching the gist (HTTP ${res.status}).`, 1);
+  const data = await res.json();
+
+  const pkgFile = data.files?.['package.tgz.b64'];
+  if (!pkgFile) {
+    throw new CliError('No package at that link (the gist has no package.tgz.b64 — not a SkillShark share).', 1);
+  }
+  let b64;
+  if (pkgFile.truncated) {
+    let raw;
+    try {
+      raw = await fetch(pkgFile.raw_url, { headers: { 'User-Agent': USER_AGENT } });
+    } catch (e) {
+      throw new CliError(`Network error fetching the package: ${e.message}`, 1);
+    }
+    if (!raw.ok) throw new CliError(`Could not fetch the package payload (HTTP ${raw.status}).`, 1);
+    b64 = (await readBodyCapped(raw, GIST_PAYLOAD_LIMIT + 1024 * 1024, 'The package payload')).toString('utf8');
+  } else {
+    b64 = pkgFile.content ?? '';
+  }
+  if (b64.length > GIST_PAYLOAD_LIMIT + 1024 * 1024) {
+    throw new CliError('The package payload exceeds the gist size limit. Refusing to continue.', 1);
+  }
+  const tarball = Buffer.from(b64.replace(/\s+/g, ''), 'base64');
+  if (tarball.length < 2 || tarball[0] !== 0x1f || tarball[1] !== 0x8b) {
+    throw new CliError(MSG.downloadIntegrity, 1);
+  }
+  return {
+    tarball,
+    owner: data.owner?.login ?? null,
+    revision: data.history?.[0]?.version ?? null,
+    description: data.description ?? '',
+  };
+}