skillshark 0.1.0

package/src/transports/repo.js

@@ -0,0 +1,98 @@
+// 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).
+import { CliError } from '../errors.js';
+import { USER_AGENT } from '../version.js';
+import { extractTarball } from '../pkg.js';
+
+export const REPO_TARBALL_LIMIT = 50 * 1024 * 1024;
+const FETCH_HEADERS = {
+  Accept: 'application/vnd.github+json',
+  'User-Agent': USER_AGENT,
+  'X-GitHub-Api-Version': '2022-11-28',
+};
+
+async function getJson(fetch, url, what) {
+  let res;
+  try {
+    res = await fetch(url, { headers: FETCH_HEADERS });
+  } catch (e) {
+    throw new CliError(`Network error reaching GitHub: ${e.message}`, 1);
+  }
+  if (res.status === 404) throw new CliError(`${what} not found (private repos aren't supported in v0.1).`, 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 for ${what} (HTTP ${res.status}).`, 1);
+  return res.json();
+}
+
+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. Put less in, or install a deeper path.`, 1);
+    }
+    chunks.push(buf);
+  }
+  return Buffer.concat(chunks);
+}
+
+// Map a codeload entry path onto the requested subtree:
+// strip the "<repo>-<ref>/" prefix, then select under `subPath` (or everything).
+// A file `subPath` maps to its basename. Returns null to skip the entry.
+export function subtreeMapper(subPath) {
+  const want = subPath ? subPath.split('/').filter(Boolean) : [];
+  return (cleanedPath) => {
+    const segs = cleanedPath.split('/').filter(Boolean);
+    if (segs.length <= 1) return null; // the prefix dir itself
+    const rest = segs.slice(1);
+    if (want.length === 0) return rest.join('/');
+    if (rest.length < want.length) return null;
+    for (let i = 0; i < want.length; i++) {
+      if (rest[i] !== want[i]) return null;
+    }
+    if (rest.length === want.length) return rest[rest.length - 1]; // subPath IS a file
+    return rest.slice(want.length).join('/');
+  };
+}
+
+// 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 }) {
+  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}`);
+      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}`,
+    );
+    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);
+  }
+  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

@@ -0,0 +1,103 @@
+// Terminal output + interactive prompts. Glyphs and color are decoration,
+// never information — everything must read fine on a dumb pipe.
+import pc from 'picocolors';
+import path from 'node:path';
+import os from 'node:os';
+import { formatFp8 } from './fingerprint.js';
+
+export function humanSize(bytes) {
+  if (bytes >= 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(bytes / 1024).toFixed(1)} KB`;
+}
+
+export function plural(n, word) {
+  return `${n} ${word}${n === 1 ? '' : 's'}`;
+}
+
+// Show a path the way the user thinks of it: relative inside cwd, ~ for home.
+export function displayPath(p, { cwd = process.cwd(), home = os.homedir() } = {}) {
+  const abs = path.resolve(p);
+  if (abs === cwd) return '.';
+  if (abs.startsWith(cwd + path.sep)) return path.relative(cwd, abs);
+  if (abs === home) return '~';
+  if (abs.startsWith(home + path.sep)) return `~${path.sep}${path.relative(home, abs)}`;
+  return abs;
+}
+
+export function makeUi({ stdout = process.stdout, stderr = process.stderr, color = undefined } = {}) {
+  const enabled = color ?? (Boolean(stdout.isTTY) && !process.env.NO_COLOR);
+  const c = pc.createColors(enabled);
+  const write = (stream, s) => stream.write(s + '\n');
+  return {
+    colors: c,
+    out: (s = '') => write(stdout, s),
+    raw: (s) => stdout.write(s),
+    err: (s = '') => write(stderr, s),
+    ok: (s) => write(stdout, `  ${c.green('✓')} ${s}`),
+    warn: (s) => write(stdout, `  ${c.yellow('⚠')} ${s}`),
+    info: (s) => write(stdout, `  ${c.cyan('ⓘ')} ${s}`),
+    fail: (s) => write(stderr, `  ${c.red('✗')} ${s}`),
+  };
+}
+
+// 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;
+  const typeLabel = manifest.type.charAt(0).toUpperCase() + manifest.type.slice(1);
+  ui.out(`  ${typeLabel}:  ${c.bold(manifest.name)}`);
+  ui.out(`  Type:   ${manifest.type.padEnd(14)} Agent: ${manifest.agent || '—'}`);
+  ui.out(`  Size:   ${humanSize(manifest.totalSize ?? manifest.files.reduce((n, f) => n + (f.size ?? 0), 0)).padEnd(14)} Files: ${manifest.files.length}`);
+  let fpLine = `  Fingerprint: ${formatFp8(fingerprint)}`;
+  if (fpFromLink) fpLine += `  ${c.green('✓')} matches #fp in the link`;
+  ui.out(fpLine);
+  if (manifest.description) ui.out(`  ${c.dim(manifest.description)}`);
+  ui.out('');
+  renderFileTree(ui, manifest);
+  ui.out('');
+  const execs = manifest.files.filter((f) => f.executable);
+  if (execs.length) {
+    ui.warn(`${plural(execs.length, 'executable script')}: ${execs.map((f) => f.path).join(', ')}`);
+    ui.out('    SkillShark will not run them and will install them without the executable');
+    ui.out('    bit (re-run with --allow-exec to keep it).');
+  }
+  if (externalRefs?.length) {
+    ui.warn(`references files outside the package (may not work standalone): ${externalRefs.join(', ')}`);
+  }
+  if (Array.isArray(manifest.dependencies) && manifest.dependencies.length) {
+    ui.info(`declares dependencies (informational only, never auto-installed): ${JSON.stringify(manifest.dependencies)}`);
+  }
+}
+
+export function renderFileTree(ui, manifest) {
+  const c = ui.colors;
+  ui.out(`    ${c.bold(manifest.name)}/`);
+  const files = manifest.files;
+  const width = Math.max(...files.map((f) => f.path.length)) + 3;
+  files.forEach((f, i) => {
+    const glyph = i === files.length - 1 ? '└──' : '├──';
+    const exec = f.executable ? `   ${c.yellow('(executable)')}` : '';
+    ui.out(`    ${glyph} ${f.path.padEnd(width)}${humanSize(f.size ?? 0)}${exec}`);
+  });
+}
+
+// Interactive prompt seam — the install pipeline calls deps.prompts.* so tests
+// can stub it; this is the real @clack implementation, loaded lazily so the
+// receive path in non-TTY/CI never even imports it.
+export async function realPrompts() {
+  const clack = await import('@clack/prompts');
+  return {
+    async select({ message, options }) {
+      const value = await clack.select({
+        message,
+        options: options.map((o) => ({ value: o.value, label: o.label, hint: o.hint })),
+      });
+      if (clack.isCancel(value)) return null;
+      return value;
+    },
+    async confirm({ message }) {
+      const value = await clack.confirm({ message });
+      if (clack.isCancel(value)) return null;
+      return value;
+    },
+  };
+}

package/src/version.js

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