skillshark 0.1.0 → 0.3.0

package/src/interactive.js

@@ -0,0 +1,189 @@
+// The interactive session: `skillshark` with no arguments (TTY only) drops
+// into a guided menu; bare `share`/`install`/`inspect`/`revoke` run their
+// wizard one-shot. Built on @clack/prompts — every flow ends in the same
+// audited pipelines as the flag-driven CLI; the wizard only collects answers.
+import { CliError } from './errors.js';
+import { discoverAll } from './discover.js';
+import { parseSource } from './source.js';
+import { runShare, runRevoke } from './share.js';
+import { runInstall, runInspect } from './install.js';
+import { loadConfig } from './config.js';
+import { displayPath } from './ui.js';
+import { AGENTS } from './agents.js';
+import { VERSION } from './version.js';
+
+const FIN = [
+  '     |\\',
+  '     | \\',
+  '  ~~~;~~\\~~~~',
+];
+
+async function ux() {
+  const clack = await import('@clack/prompts');
+  const pc = (await import('picocolors')).default;
+  return { clack, pc };
+}
+
+function bail(clack, value) {
+  return value === null || value === undefined || clack.isCancel(value);
+}
+
+// --- share wizard --------------------------------------------------------------
+
+async function wizardShare(deps, { clack, pc }) {
+  const found = await deps.ui.spin('Scanning for shareable artifacts', () => discoverAll(deps));
+  if (!found.length) {
+    clack.log.warn('Nothing shareable here or in your home directory. Create a skill first (e.g. .claude/skills/<name>/SKILL.md).');
+    return { status: 'cancelled' };
+  }
+  const pick = await clack.select({
+    message: `Share which artifact? ${pc.dim(`(${found.length} found)`)}`,
+    maxItems: 12,
+    options: found.map((a) => ({
+      value: a.root,
+      label: a.name,
+      hint: `${AGENTS[a.agent]?.label ?? a.agent} ${a.type} · ${a.scope === 'global' ? '~' : displayPath(a.root, deps)}`,
+    })),
+  });
+  if (bail(clack, pick)) return { status: 'cancelled' };
+
+  const expires = await clack.select({
+    message: 'Advisory expiry (installers refuse after this; the gist lives until you revoke):',
+    initialValue: '7d',
+    options: [
+      { value: '30m', label: '30 minutes' },
+      { value: '6h', label: '6 hours' },
+      { value: '24h', label: '24 hours' },
+      { value: '7d', label: '7 days', hint: 'default' },
+      { value: '30d', label: '30 days' },
+    ],
+  });
+  if (bail(clack, expires)) return { status: 'cancelled' };
+
+  return runShare(pick, { expires }, deps);
+}
+
+// --- install / inspect wizards ----------------------------------------------------
+
+async function askSource(deps, { clack }) {
+  for (;;) {
+    const source = await clack.text({
+      message: 'Paste the link (gist URL, bare id, or gh:owner/repo[/path][@ref]):',
+      placeholder: 'https://gist.github.com/…#fp=…',
+    });
+    if (bail(clack, source)) return null;
+    try {
+      parseSource(String(source).trim());
+      return String(source).trim();
+    } catch (err) {
+      if (err instanceof CliError) {
+        clack.log.error(err.message);
+        continue;
+      }
+      throw err;
+    }
+  }
+}
+
+async function wizardInstall(deps, u) {
+  const source = await askSource(deps, u);
+  if (source === null) return { status: 'cancelled' };
+  return runInstall(source, {}, deps);
+}
+
+async function wizardInspect(deps, u) {
+  const { clack } = u;
+  const source = await askSource(deps, u);
+  if (source === null) return { status: 'cancelled' };
+  await runInspect(source, {}, deps);
+  const next = await clack.select({
+    message: 'And now?',
+    options: [
+      { value: 'install', label: 'Install it' },
+      { value: 'done', label: 'Done' },
+    ],
+  });
+  if (!bail(clack, next) && next === 'install') {
+    return runInstall(source, {}, deps);
+  }
+  return { status: 'inspected' };
+}
+
+// --- revoke wizard -----------------------------------------------------------------
+
+async function wizardRevoke(deps, { clack, pc }) {
+  const cfg = await loadConfig(deps.configDir);
+  let idOrName = null;
+  if (cfg.shares.length) {
+    const pick = await clack.select({
+      message: 'Revoke which share?',
+      maxItems: 12,
+      options: [
+        ...cfg.shares.map((s) => ({
+          value: s.id,
+          label: s.name,
+          hint: `${s.id.slice(0, 12)}… · expires ${s.expiresAt ? s.expiresAt.slice(0, 10) : 'never'}`,
+        })),
+        { value: '__manual', label: 'Enter a gist id or name…' },
+      ],
+    });
+    if (bail(clack, pick)) return { status: 'cancelled' };
+    idOrName = pick === '__manual' ? null : pick;
+  }
+  if (idOrName === null) {
+    const entered = await clack.text({ message: 'Gist id (or share name):' });
+    if (bail(clack, entered) || !String(entered).trim()) return { status: 'cancelled' };
+    idOrName = String(entered).trim();
+  }
+  clack.log.warn(pc.yellow('Revoking deletes the gist — anyone holding the link loses access immediately.'));
+  return runRevoke(idOrName, {}, deps);
+}
+
+// --- the session --------------------------------------------------------------------
+
+const WIZARDS = {
+  share: wizardShare,
+  install: wizardInstall,
+  inspect: wizardInspect,
+  revoke: wizardRevoke,
+};
+
+// action: run a single wizard (bare `skillshark share` etc.); null: full menu.
+export async function runInteractive(deps, action = null) {
+  const u = await ux();
+  const { clack, pc } = u;
+
+  clack.intro(`${pc.cyan(FIN.join('\n   '))}\n   ${pc.bold('skillshark')} ${pc.dim(`v${VERSION} — share agent skills like files`)}`);
+
+  if (action) {
+    const result = await WIZARDS[action](deps, u);
+    clack.outro(result?.status === 'cancelled' ? 'Nothing happened. 🦈' : 'Done. 🦈');
+    return 0;
+  }
+
+  for (;;) {
+    const choice = await clack.select({
+      message: 'What are we doing?',
+      options: [
+        { value: 'share', label: 'Share', hint: 'package a local skill → unlisted link' },
+        { value: 'install', label: 'Install', hint: 'from a link or repo path' },
+        { value: 'inspect', label: 'Inspect', hint: 'look before you leap' },
+        { value: 'revoke', label: 'Revoke', hint: 'kill a link you shared' },
+        { value: 'quit', label: 'Quit' },
+      ],
+    });
+    if (bail(clack, choice) || choice === 'quit') break;
+    try {
+      await WIZARDS[choice](deps, u);
+    } catch (err) {
+      if (err instanceof CliError) {
+        clack.log.error(err.message);
+      } else {
+        throw err;
+      }
+    }
+    clack.log.message('');
+  }
+  clack.outro('Swim safe. 🦈');
+  return 0;
+}

package/src/share.js

@@ -3,6 +3,7 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { CliError } from './errors.js';
+import { resolveHost, DEFAULT_HOST } from './source.js';
 import { resolveShareArg, collectFiles, inferMetadata, findExternalRefs } from './discover.js';
 import { buildTarball } from './pkg.js';
 import { treeFingerprint, fp8 } from './fingerprint.js';
@@ -153,14 +154,22 @@ export async function runShare(arg, opts, deps) {
     } 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}`;
+  const host = resolveHost(opts, deps);
+  const { id, revision, htmlUrl } = await ui.spin('Uploading as a secret gist', () =>
+    createGist({
+      manifestJson,
+      primaryDoc,
+      tarballB64: b64,
+      description: gistDescription({ name: manifest.name, agent: manifest.agent, type: manifest.type, fp8: shortFp }),
+      ghApi: deps.ghApi,
+      host,
+    }));
+  // github.com gets the short canonical form; enterprise hosts keep the
+  // html_url GitHub handed back (subdomain isolation varies per install)
+  const base = host === DEFAULT_HOST ? `https://gist.github.com/${id}` : (htmlUrl ?? `https://${host}/gist/${id}`);
+  const url = `${base}#fp=${shortFp}`;
+  // the paste-and-go line: receivers run this with zero setup
+  const installCommand = `npx skillshark install '${url}'`;
 
   await addShareRecord(deps.configDir, {
     id,
@@ -168,37 +177,41 @@ export async function runShare(arg, opts, deps) {
     url,
     revision,
     expiresAt: manifest.expiresAt,
+    ...(host !== DEFAULT_HOST ? { host } : {}),
   });
 
   let copied = false;
   if (!opts.noClipboard && deps.clipboard) {
-    copied = await deps.clipboard(url);
+    copied = await deps.clipboard(installCommand);
   }
 
   if (opts.json) {
     ui.out(JSON.stringify({
       id,
       url,
+      installCommand,
       revision,
       expiresAt: manifest.expiresAt,
       fingerprint,
       size: manifest.totalSize,
       files: manifest.files.map((f) => f.path),
+      ...(host !== DEFAULT_HOST ? { host } : {}),
     }));
   } 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}`);
+    if (copied) ui.ok(`Install one-liner copied to clipboard — they just paste it · advisory expiry in ${expires.label}`);
     else ui.out(`  Advisory expiry in ${expires.label}`);
     ui.out('');
-    ui.out(`  ${url}`);
+    ui.out(`  ${installCommand}`);
     ui.out('');
-    ui.out('  They run:   skillshark install <the link>     (no GitHub account needed)');
-    ui.out(`  Undo:       skillshark revoke ${manifest.name}               (deletes the gist)`);
+    const who = host === DEFAULT_HOST ? '(no GitHub account needed)' : `(needs gh auth on ${host})`;
+    ui.out(`  Link only:  ${url}   ${who}`);
+    ui.out(`  Undo:       skillshark revoke ${manifest.name}   (deletes the gist)`);
   }
-  return { status: 'shared', id, url, fingerprint };
+  return { status: 'shared', id, url, installCommand, fingerprint };
 }
 
 // --- revoke (§4.4) -----------------------------------------------------------
@@ -207,6 +220,7 @@ export async function runRevoke(idOrName, opts, deps) {
   const ui = deps.ui;
   let id = null;
   let label = idOrName;
+  let host = resolveHost(opts, deps);
   if (/^[0-9a-f]{20,32}$/.test(idOrName)) {
     id = idOrName;
   } else {
@@ -214,9 +228,14 @@ export async function runRevoke(idOrName, opts, deps) {
     if (rec) {
       id = rec.id;
       label = `${rec.name} (${rec.id})`;
+      if (rec.host) host = rec.host; // enterprise share → revoke on its host
     } else {
-      // cache miss → ask gh for our skillshark gists
-      const out = await deps.ghApi(['gists', '--paginate']);
+      // cache miss → ask gh for our skillshark gists (on the chosen host)
+      const out = await deps.ghApi([
+        ...(host !== DEFAULT_HOST ? ['--hostname', host] : []),
+        'gists',
+        '--paginate',
+      ]);
       let gists;
       try {
         gists = JSON.parse(out);
@@ -241,7 +260,7 @@ export async function runRevoke(idOrName, opts, deps) {
       return { status: 'cancelled' };
     }
   }
-  await deleteGist(id, { ghApi: deps.ghApi });
+  await deleteGist(id, { ghApi: deps.ghApi, host });
   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".`);

package/src/source.js

@@ -1,29 +1,51 @@
 // §7.3 — source parsing. Accepted forms:
 //   https://gist.github.com/<id>            (optionally <user>/<id>, optionally #fp=<hex>)
-//   <20-32 char hex gist id>
+//   https://gist.<ghes-host>/<id>           GitHub Enterprise, subdomain isolation
+//   https://<ghes-host>/gist/<id>           GitHub Enterprise, path form
+//   <20-32 char hex gist id>                (host from --host / GH_HOST, default github.com)
 //   gh:owner/repo[/deep/path][@ref]         (ref = branch, tag, or SHA; split on the LAST "@")
 import { CliError } from './errors.js';
 
+export const DEFAULT_HOST = 'github.com';
+
 const USAGE = `Unrecognized source. Accepted forms:
   https://gist.github.com/8a1bc94ef23d4b6a9c01e57f8d2a4b3c#fp=3f9a7c21
+  https://ghe.example.com/gist/8a1bc94ef23d4b6a9c01e57f8d2a4b3c#fp=3f9a7c21
   8a1bc94ef23d4b6a9c01e57f8d2a4b3c
   gh:owner/repo[/deep/path][@ref]`;
 
 const NAME_RE = /^[A-Za-z0-9_.-]+$/;
+const HOST_RE = /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$/i;
+
+// The host a command should talk to: explicit flag → env → github.com.
+export function resolveHost(opts = {}, deps = {}) {
+  const host = opts.host || deps.env?.SKILLSHARK_HOST || deps.env?.GH_HOST || DEFAULT_HOST;
+  if (!HOST_RE.test(host)) throw new CliError(`Invalid --host "${host}".`, 2);
+  return host.toLowerCase();
+}
 
-export function parseSource(input) {
+export function parseSource(input, { defaultHost = DEFAULT_HOST } = {}) {
   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}))?$/,
+  // gist.<host>/<id> — github.com and GHES-with-subdomain-isolation alike
+  let m = s.match(
+    /^https:\/\/gist\.([a-z0-9.-]+)\/(?:([A-Za-z0-9-]+)\/)?([0-9a-f]{20,32})\/?(?:#fp=([0-9a-f]{8,64}))?$/i,
+  );
+  if (m) {
+    return { kind: 'gist', id: m[3], fp: m[4] ?? null, host: m[1].toLowerCase() };
+  }
+
+  // <host>/gist/<id> — GHES path form
+  m = s.match(
+    /^https:\/\/([a-z0-9.-]+)\/gist\/(?:([A-Za-z0-9-]+)\/)?([0-9a-f]{20,32})\/?(?:#fp=([0-9a-f]{8,64}))?$/i,
   );
-  if (gistUrl) {
-    return { kind: 'gist', id: gistUrl[2], fp: gistUrl[3] ?? null };
+  if (m && m[1].toLowerCase() !== 'github.com') {
+    return { kind: 'gist', id: m[3], fp: m[4] ?? null, host: m[1].toLowerCase() };
   }
 
   if (/^[0-9a-f]{20,32}$/.test(s)) {
-    return { kind: 'gist', id: s, fp: null };
+    return { kind: 'gist', id: s, fp: null, host: defaultHost };
   }
 
   if (s.startsWith('gh:')) {
@@ -43,6 +65,7 @@ export function parseSource(input) {
         repo: segs[1],
         path: segs.length > 2 ? segs.slice(2).join('/') : null,
         ref,
+        host: defaultHost,
       };
     }
   }
@@ -51,8 +74,9 @@ export function parseSource(input) {
 }
 
 export function formatSource(src) {
-  if (src.kind === 'gist') return `gist:${src.id}`;
+  const hostTag = src.host && src.host !== DEFAULT_HOST ? `${src.host}:` : '';
+  if (src.kind === 'gist') return `gist:${hostTag}${src.id}`;
   const p = src.path ? `/${src.path}` : '';
   const r = src.ref ? `@${src.ref}` : '';
-  return `gh:${src.owner}/${src.repo}${p}${r}`;
+  return `gh:${hostTag}${src.owner}/${src.repo}${p}${r}`;
 }

package/src/transports/gist.js

@@ -1,12 +1,19 @@
 // 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).
+// public github.com receive path is ANONYMOUS https only — it must never
+// invoke gh (§0.3). GitHub Enterprise links are the deliberate exception:
+// privacy means everything rides the receiver's own gh auth and no anonymous
+// request ever leaves for the enterprise host.
 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';
+import { DEFAULT_HOST } from '../source.js';
 
 export const GIST_PAYLOAD_LIMIT = 5 * 1024 * 1024; // encoded bytes (§4.1)
+// the gists API truncates inline file content at ~1 MB; on enterprise hosts we
+// can't fall back to an anonymous raw_url fetch, so shares are capped honestly
+export const ENTERPRISE_INLINE_LIMIT = 900 * 1024;
 const FETCH_HEADERS = {
   Accept: 'application/vnd.github+json',
   'User-Agent': USER_AGENT,
@@ -22,9 +29,19 @@ export function gistDescription({ name, agent, type, fp8 }) {
   return `skillshark: ${name} (${kind}) · fp ${fp8}`;
 }
 
+function hostFlags(host) {
+  return host && host !== DEFAULT_HOST ? ['--hostname', host] : [];
+}
+
 // 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 }) {
+export async function createGist({ manifestJson, primaryDoc, tarballB64, description, ghApi, host = DEFAULT_HOST }) {
+  if (host !== DEFAULT_HOST && tarballB64.length > ENTERPRISE_INLINE_LIMIT) {
+    throw new CliError(
+      `That's too big for an enterprise gist share (~${Math.floor(ENTERPRISE_INLINE_LIMIT / 1024)} KB encoded cap — the API truncates larger files and enterprise receivers can't fetch around it anonymously). Put it in a repo on ${host} instead.`,
+      2,
+    );
+  }
   const files = { 'SKILLSHARK.json': { content: manifestJson } };
   if (primaryDoc && primaryDoc.content.trim()) {
     files[path.basename(primaryDoc.name)] = { content: primaryDoc.content };
@@ -36,7 +53,7 @@ export async function createGist({ manifestJson, primaryDoc, tarballB64, descrip
   const bodyFile = path.join(tmpDir, 'gist-body.json');
   try {
     await writeFile(bodyFile, JSON.stringify(body));
-    const stdout = await ghApi(['gists', '--method', 'POST', '--input', bodyFile]);
+    const stdout = await ghApi([...hostFlags(host), 'gists', '--method', 'POST', '--input', bodyFile]);
     let parsed;
     try {
       parsed = JSON.parse(stdout);
@@ -44,14 +61,14 @@ export async function createGist({ manifestJson, primaryDoc, tarballB64, descrip
       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 };
+    return { id: parsed.id, revision: parsed.history?.[0]?.version ?? null, htmlUrl: parsed.html_url ?? null };
   } finally {
     await rm(tmpDir, { recursive: true, force: true });
   }
 }
 
-export async function deleteGist(id, { ghApi }) {
-  await ghApi(['--method', 'DELETE', `gists/${id}`]);
+export async function deleteGist(id, { ghApi, host = DEFAULT_HOST }) {
+  await ghApi([...hostFlags(host), '--method', 'DELETE', `gists/${id}`]);
 }
 
 // --- receive side (anonymous fetch, no gh — ever) ---------------------------
@@ -70,25 +87,50 @@ async function readBodyCapped(res, cap, what) {
   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);
+export async function fetchGistPackage(id, { fetch, host = DEFAULT_HOST, ghApi = null }) {
+  let data;
+  if (host !== DEFAULT_HOST) {
+    // GitHub Enterprise: private by nature. Everything goes through the
+    // receiver's own gh auth; no anonymous request touches the host.
+    if (!ghApi) throw new CliError(`Can't reach ${host} without gh.`, 2);
+    let stdout;
+    try {
+      stdout = await ghApi(['--hostname', host, `gists/${id}`]);
+    } catch (err) {
+      if (err instanceof CliError && /404/.test(err.message)) throw new CliError(MSG.gistDeleted, 1);
+      throw err;
+    }
+    try {
+      data = JSON.parse(stdout);
+    } catch {
+      throw new CliError(`Unexpected response from ${host} while fetching the gist.`, 1);
+    }
+  } else {
+    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);
+    data = await res.json();
   }
-  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 && host !== DEFAULT_HOST) {
+    throw new CliError(
+      `This enterprise share is too large to fetch inline (the ${host} API truncates files past ~1 MB). Ask the sender to share it as a repo path on ${host} instead.`,
+      1,
+    );
+  }
   if (pkgFile.truncated) {
     let raw;
     try {

package/src/transports/repo.js

@@ -1,9 +1,12 @@
-// Repo transport (install-only in v0.1): gh:owner/repo[/path][@ref], fetched
-// anonymously from api.github.com + codeload. The one integrity anchor is the
-// commit SHA; #fp= does not apply here (§4.2).
+// Repo transport (install-only): gh:owner/repo[/path][@ref], fetched
+// anonymously from api.github.com + codeload for public github.com, or
+// entirely through the receiver's gh auth for GitHub Enterprise hosts —
+// no anonymous request ever leaves for an enterprise host. The integrity
+// anchor is the commit SHA; #fp= does not apply here (§4.2).
 import { CliError } from '../errors.js';
 import { USER_AGENT } from '../version.js';
 import { extractTarball } from '../pkg.js';
+import { DEFAULT_HOST } from '../source.js';
 
 export const REPO_TARBALL_LIMIT = 50 * 1024 * 1024;
 const FETCH_HEADERS = {
@@ -60,38 +63,68 @@ export function subtreeMapper(subPath) {
   };
 }
 
-// Resolve ref → commit SHA (pinned installs skip the API entirely), download
-// the codeload tarball, and extract just the subtree through the §7.2 guards.
-export async function fetchRepoTree({ owner, repo, path: subPath, ref }, destDir, { fetch }) {
+async function ghJson(ghApi, host, apiPath, what) {
+  let stdout;
+  try {
+    stdout = await ghApi(['--hostname', host, apiPath]);
+  } catch (err) {
+    if (err instanceof CliError && /404/.test(err.message)) {
+      throw new CliError(`${what} not found on ${host}.`, 1);
+    }
+    throw err;
+  }
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    throw new CliError(`Unexpected response from ${host} for ${what}.`, 1);
+  }
+}
+
+// Resolve ref → commit SHA (pinned public installs skip the API entirely),
+// download the tarball, and extract just the subtree through the §7.2 guards.
+export async function fetchRepoTree({ owner, repo, path: subPath, ref, host = DEFAULT_HOST }, destDir, { fetch, ghApi = null }) {
+  const enterprise = host !== DEFAULT_HOST;
+  if (enterprise && !ghApi) throw new CliError(`Can't reach ${host} without gh.`, 2);
   let sha;
   if (ref && /^[0-9a-f]{40}$/.test(ref)) {
     sha = ref;
   } else {
     let resolvedRef = ref;
     if (!resolvedRef) {
-      const repoInfo = await getJson(fetch, `https://api.github.com/repos/${owner}/${repo}`, `Repository ${owner}/${repo}`);
+      const repoInfo = enterprise
+        ? await ghJson(ghApi, host, `repos/${owner}/${repo}`, `Repository ${owner}/${repo}`)
+        : await getJson(fetch, `https://api.github.com/repos/${owner}/${repo}`, `Repository ${owner}/${repo}`);
       resolvedRef = repoInfo.default_branch;
       if (!resolvedRef) throw new CliError(`Repository ${owner}/${repo} has no default branch.`, 1);
     }
-    const commit = await getJson(
-      fetch,
-      `https://api.github.com/repos/${owner}/${repo}/commits/${encodeURIComponent(resolvedRef)}`,
-      `Ref "${resolvedRef}" in ${owner}/${repo}`,
-    );
+    const commitPath = `repos/${owner}/${repo}/commits/${encodeURIComponent(resolvedRef)}`;
+    const commit = enterprise
+      ? await ghJson(ghApi, host, commitPath, `Ref "${resolvedRef}" in ${owner}/${repo}`)
+      : await getJson(fetch, `https://api.github.com/${commitPath}`, `Ref "${resolvedRef}" in ${owner}/${repo}`);
     sha = commit.sha;
     if (!sha) throw new CliError(`Could not resolve "${resolvedRef}" to a commit in ${owner}/${repo}.`, 1);
   }
 
-  let res;
-  try {
-    res = await fetch(`https://codeload.github.com/${owner}/${repo}/tar.gz/${sha}`, {
-      headers: { 'User-Agent': USER_AGENT },
-    });
-  } catch (e) {
-    throw new CliError(`Network error downloading the repo tarball: ${e.message}`, 1);
+  let tarball;
+  if (enterprise) {
+    // gh follows the tarball redirect and emits the bytes on stdout
+    tarball = await ghApi(['--hostname', host, `repos/${owner}/${repo}/tarball/${sha}`], { binary: true });
+    if (!Buffer.isBuffer(tarball)) tarball = Buffer.from(tarball);
+    if (tarball.length > REPO_TARBALL_LIMIT) {
+      throw new CliError(`The repo tarball exceeds the ${Math.floor(REPO_TARBALL_LIMIT / (1024 * 1024))} MB limit.`, 1);
+    }
+  } else {
+    let res;
+    try {
+      res = await fetch(`https://codeload.github.com/${owner}/${repo}/tar.gz/${sha}`, {
+        headers: { 'User-Agent': USER_AGENT },
+      });
+    } catch (e) {
+      throw new CliError(`Network error downloading the repo tarball: ${e.message}`, 1);
+    }
+    if (!res.ok) throw new CliError(`Could not download ${owner}/${repo}@${sha.slice(0, 7)} (HTTP ${res.status}).`, 1);
+    tarball = await readBodyCapped(res, REPO_TARBALL_LIMIT, 'The repo tarball');
   }
-  if (!res.ok) throw new CliError(`Could not download ${owner}/${repo}@${sha.slice(0, 7)} (HTTP ${res.status}).`, 1);
-  const tarball = await readBodyCapped(res, REPO_TARBALL_LIMIT, 'The repo tarball');
 
   await extractTarball(tarball, destDir, { transformPath: subtreeMapper(subPath) });
   return { sha };

package/src/ui.js

@@ -37,9 +37,29 @@ export function makeUi({ stdout = process.stdout, stderr = process.stderr, color
     warn: (s) => write(stdout, `  ${c.yellow('⚠')} ${s}`),
     info: (s) => write(stdout, `  ${c.cyan('ⓘ')} ${s}`),
     fail: (s) => write(stderr, `  ${c.red('✗')} ${s}`),
+    // network-op wrapper; the TTY entrypoint swaps in a real spinner
+    spin: async (_label, fn) => fn(),
   };
 }
 
+// Replace ui.spin with an animated @clack spinner (TTY only).
+export async function attachSpinner(ui) {
+  const clack = await import('@clack/prompts');
+  ui.spin = async (label, fn) => {
+    const s = clack.spinner();
+    s.start(label);
+    try {
+      const result = await fn();
+      s.stop(`${label} — done`);
+      return result;
+    } catch (err) {
+      s.stop(`${label} — failed`, 1);
+      throw err;
+    }
+  };
+  return ui;
+}
+
 // The install/inspect preview, rendered only from verified bytes (§4.2 step 5).
 export function renderPreview(ui, { manifest, fingerprint, fpFromLink, externalRefs }) {
   const c = ui.colors;
@@ -99,5 +119,10 @@ export async function realPrompts() {
       if (clack.isCancel(value)) return null;
       return value;
     },
+    async text({ message, placeholder }) {
+      const value = await clack.text({ message, placeholder });
+      if (clack.isCancel(value)) return null;
+      return String(value ?? '').trim();
+    },
   };
 }

package/src/version.js

@@ -1,2 +1,2 @@
-export const VERSION = '0.1.0';
+export const VERSION = '0.3.0';
 export const USER_AGENT = `skillshark/${VERSION}`;