mulmoclaude 0.6.2 → 0.6.4

package/server/workspace/skills/external/clone.ts

@@ -0,0 +1,129 @@
+// Git sparse-checkout helper for the external-skill catalog
+// (#1383 / #1335 PR-C).
+//
+// Responsibilities:
+//   - Clone or fetch into a workspace-EXTERNAL scratch dir keyed by
+//     hash(url) so multiple installs of the same URL (with different
+//     subpaths) share one `.git/`.
+//   - Apply a sparse-checkout pattern when `subpath` is provided so
+//     huge multi-skill repos don't materialise files we won't use.
+//   - Return the resolved commit SHA + cache dir so the install
+//     layer can scan for SKILL.md and write its own `.source.json`.
+//
+// The git binary is invoked through `execFile` (no shell) and the
+// runner is injectable via `deps.runGit` so unit tests can fake the
+// filesystem layout without ever shelling out.
+
+import { execFile } from "node:child_process";
+import { mkdir, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import { ONE_MINUTE_MS } from "../../../utils/time.js";
+import { parseGitHubHttpsUrl, urlCacheKey } from "./id.js";
+
+const execFileP = promisify(execFile);
+
+const GIT_OP_TIMEOUT_MS = ONE_MINUTE_MS;
+
+export interface CloneOptions {
+  url: string;
+  subpath?: string;
+  /** Branch / tag / SHA to fetch. Default: "HEAD". */
+  ref?: string;
+}
+
+export interface CloneResult {
+  /** Absolute path to the populated cache dir (contains `.git/` plus
+   *  the checked-out tree). */
+  cacheDir: string;
+  /** Commit SHA pointed to by `HEAD` after fetch. */
+  sha: string;
+}
+
+export type RunGit = (args: readonly string[]) => Promise<{ stdout: string; stderr: string }>;
+
+/** Default git runner: shells out to `git` on PATH with no shell
+ *  involvement (execFile, not exec). The workspace init already
+ *  assumes `git` is available (see `server/workspace/workspace.ts`),
+ *  so this isn't a new dependency. */
+export const defaultRunGit: RunGit = async (args) => execFileP("git", args.slice(), { timeout: GIT_OP_TIMEOUT_MS });
+
+/** Default scratch root: `~/.cache/mulmoclaude/sources/`. Kept
+ *  outside the workspace so `.git/` clutter doesn't end up in the
+ *  user's workspace git history or Obsidian sync. */
+export function defaultCacheRoot(): string {
+  return path.join(homedir(), ".cache", "mulmoclaude", "sources");
+}
+
+export interface CloneDeps {
+  cacheRoot?: string;
+  runGit?: RunGit;
+}
+
+/** One-time repo creation: `git init` + `remote add`. No-op once
+ *  `.git/` exists (re-installs reuse the existing clone). */
+async function initRepoOnce(cacheDir: string, url: string, runGit: RunGit): Promise<void> {
+  if (existsSync(path.join(cacheDir, ".git"))) return;
+  await runGit(["init", cacheDir]);
+  await runGit(["-C", cacheDir, "remote", "add", "origin", url]);
+}
+
+/** Apply sparse-checkout config to match the CURRENT request — runs
+ *  on every call, not just first init. Without this, re-installing
+ *  the same URL with a different (or absent) `subpath` would keep the
+ *  stale pattern from the first install, so `git checkout` stays
+ *  constrained and discovery wrongly reports `no-skills`. Caller
+ *  guarantees `subpath` is already sanitised. */
+async function applySparseCheckout(cacheDir: string, subpath: string | undefined, runGit: RunGit): Promise<void> {
+  if (!subpath) {
+    // Lift any constraint left by a previous subpath install.
+    await runGit(["-C", cacheDir, "config", "core.sparseCheckout", "false"]);
+    return;
+  }
+  await runGit(["-C", cacheDir, "config", "core.sparseCheckout", "true"]);
+  // sparse-checkout pattern is one entry per line; we want the
+  // entire subpath subtree.
+  const sparseFile = path.join(cacheDir, ".git", "info", "sparse-checkout");
+  await mkdir(path.dirname(sparseFile), { recursive: true });
+  await writeFile(sparseFile, `${subpath}/*\n`);
+}
+
+/** Fetch `ref` at depth 1, check it out, and return the resolved
+ *  40-hex SHA. Throws if `rev-parse` yields anything unexpected. */
+async function fetchAndResolveSha(cacheDir: string, ref: string, runGit: RunGit): Promise<string> {
+  // `--depth=1` keeps the scratch dir small; we only need the current
+  // tree, never history. `--no-tags` avoids pulling release-tag noise.
+  await runGit(["-C", cacheDir, "fetch", "--depth=1", "--no-tags", "origin", ref]);
+  await runGit(["-C", cacheDir, "checkout", "FETCH_HEAD"]);
+  const { stdout: shaRaw } = await runGit(["-C", cacheDir, "rev-parse", "HEAD"]);
+  const sha = shaRaw.trim();
+  if (!/^[0-9a-f]{40}$/.test(sha)) {
+    throw new Error(`git rev-parse returned unexpected output: ${JSON.stringify(shaRaw)}`);
+  }
+  return sha;
+}
+
+/** Initialise (or refresh) a scratch clone for the given URL and
+ *  return the cache dir + resolved SHA. Idempotent: a second call
+ *  with the same URL only fetches new commits and re-checks-out. */
+export async function cloneOrUpdate(opts: CloneOptions, deps: CloneDeps = {}): Promise<CloneResult> {
+  // Defense-in-depth: the install layer already validates via
+  // `deriveRepoId`, but re-checking here keeps the function safe
+  // against direct callers (tests / future refactors) so an
+  // unvalidated URL can never reach `git`.
+  if (!parseGitHubHttpsUrl(opts.url)) {
+    throw new Error(`invalid GitHub HTTPS URL: ${opts.url}`);
+  }
+  const runGit = deps.runGit ?? defaultRunGit;
+  const cacheRoot = deps.cacheRoot ?? defaultCacheRoot();
+  const cacheDir = path.join(cacheRoot, urlCacheKey(opts.url));
+
+  await mkdir(cacheDir, { recursive: true });
+  await initRepoOnce(cacheDir, opts.url, runGit);
+  await applySparseCheckout(cacheDir, opts.subpath, runGit);
+  const sha = await fetchAndResolveSha(cacheDir, opts.ref ?? "HEAD", runGit);
+  return { cacheDir, sha };
+}

package/server/workspace/skills/external/id.ts

@@ -0,0 +1,194 @@
+// ID derivation for the external-skill catalog (#1383 / #1335 PR-C).
+//
+// Inputs: a GitHub HTTPS URL + optional subpath. Outputs:
+//
+//   - `repoId`     — the directory name under `data/skills/catalog/external/`.
+//                     Built from `<owner>-<repo>` so the same repo always
+//                     resolves to the same folder regardless of which
+//                     subpath the user picked (subpath determines what
+//                     ends up INSIDE the dir, not its name).
+//   - `activeId`   — the directory name under `.claude/skills/`. Built
+//                     from `<owner>-<skillFolder>` to keep the slash-
+//                     command flat and reasonably short. When the repo
+//                     ships a single SKILL.md at root (no skillFolder),
+//                     the activeId equals the repoId.
+//
+// Both ids run through the same `safeSlug` filter the rest of the
+// catalog uses (regex whitelist + `path.basename` round-trip — CodeQL's
+// recognised path-injection sanitiser, established in PR-B).
+
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+// Slug whitelist: lowercase alnum + `-`, must start and end with alnum,
+// at least one character. Matches the convention used by `catalog.ts`'s
+// `safeSlugName` but lower-cases the input first since URLs / repo
+// names are case-insensitive on GitHub.
+//
+// The two `[a-z0-9-]` segments around the required leading + trailing
+// alnum look like nested quantifiers to the security/detect-unsafe-regex
+// rule, but each segment can only consume from a single bounded
+// character class — worst-case backtracking is linear.
+// eslint-disable-next-line security/detect-unsafe-regex -- non-overlapping classes
+const SAFE_SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+
+function sanitise(raw: string): string | null {
+  // Fail-closed denylist FIRST: anything that smells like a path
+  // operator is rejected outright. Doing the normalise step below
+  // first would silently collapse `..` → `-` and let suspicious
+  // input through as benign-looking strings (`../etc` → `etc`).
+  if (raw.includes("..") || raw.includes("/") || raw.includes("\\") || raw.includes("\0")) return null;
+  // Normalise punctuation to hyphens then trim leading + trailing
+  // separators via slice (avoids `/-+$/` which sonar flags as
+  // potentially slow even though it's bounded by `$`).
+  let lowered = raw.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+  while (lowered.startsWith("-")) lowered = lowered.slice(1);
+  while (lowered.endsWith("-")) lowered = lowered.slice(0, -1);
+  if (!SAFE_SLUG_PATTERN.test(lowered)) return null;
+  // `path.basename` round-trip — same launder used elsewhere so CodeQL
+  // recognises the result as sanitised when it flows into `path.join`.
+  const basename = path.basename(lowered);
+  return basename === lowered ? basename : null;
+}
+
+export interface ParsedGitHubUrl {
+  owner: string;
+  repo: string;
+}
+
+const GITHUB_HTTPS_RE = /^https:\/\/github\.com\/([A-Za-z0-9][A-Za-z0-9-]{0,38})\/([A-Za-z0-9._-]{1,100})(?:\.git)?\/?$/;
+
+/** Parse a GitHub HTTPS URL into owner/repo. v1 only accepts
+ *  `https://github.com/<owner>/<repo>` (optional `.git` suffix,
+ *  optional trailing slash). gitlab / SSH / private hosts are out of
+ *  scope. Returns `null` on any rejection. */
+export function parseGitHubHttpsUrl(url: string): ParsedGitHubUrl | null {
+  const match = GITHUB_HTTPS_RE.exec(url);
+  if (!match) return null;
+  const [, owner, repoRaw] = match;
+  // Strip a trailing `.git` if the regex's optional group missed it
+  // (it's already handled in the regex, but be defensive).
+  const repo = repoRaw.endsWith(".git") ? repoRaw.slice(0, -".git".length) : repoRaw;
+  return { owner, repo };
+}
+
+/** Derive the repo-level catalog directory name from URL.
+ *  `<owner>-<repo>`. Returns `null` if the URL fails parsing or the
+ *  resulting slug isn't safe (e.g. owner / repo contains only
+ *  punctuation). */
+export function deriveRepoId(url: string): string | null {
+  const parsed = parseGitHubHttpsUrl(url);
+  if (!parsed) return null;
+  return sanitise(`${parsed.owner}-${parsed.repo}`);
+}
+
+/** Derive the active-layer directory name from a URL + skillFolder.
+ *  When `skillFolder` is `null`, the skill is at repo root and the
+ *  active id equals the repoId. */
+export function deriveActiveId(url: string, skillFolder: string | null): string | null {
+  const parsed = parseGitHubHttpsUrl(url);
+  if (!parsed) return null;
+  if (skillFolder === null) {
+    return sanitise(`${parsed.owner}-${parsed.repo}`);
+  }
+  // Validate skillFolder itself first so a path-traversal-shaped
+  // input ("..", "foo/bar") fails closed before composition.
+  const folderSafe = sanitise(skillFolder);
+  if (folderSafe === null) return null;
+  return sanitise(`${parsed.owner}-${folderSafe}`);
+}
+
+/** Canonical `https://github.com/<owner>/<repo>` (lowercased, no
+ *  `.git`/trailing slash) — the identity two URLs share iff they
+ *  point at the same GitHub repo. `null` if the URL doesn't parse.
+ *  Used both for cache keying and the install-time collision guard
+ *  (distinct repos whose `repoId` punctuation-collides must be told
+ *  apart by their canonical URL, not their lossy id). */
+export function canonicalRepoUrl(url: string): string | null {
+  const parsed = parseGitHubHttpsUrl(url);
+  return parsed ? `https://github.com/${parsed.owner.toLowerCase()}/${parsed.repo.toLowerCase()}` : null;
+}
+
+/** Stable opaque hash of a URL for keying the scratch-clone cache.
+ *  Canonicalises first so the accepted variants of the same repo
+ *  (`/o/r`, `/o/r/`, `/o/r.git`, case differences) map to ONE cache
+ *  dir — otherwise a re-install via a different form would spawn a
+ *  duplicate clone and uninstall would only drop the last-recorded
+ *  variant. */
+export function urlCacheKey(url: string): string {
+  return createHash("sha256")
+    .update(canonicalRepoUrl(url) ?? url)
+    .digest("hex")
+    .slice(0, 16);
+}
+
+// Shape of a `deriveRepoId` output (`<owner>-<repo>` lowercased). The
+// two `[a-z0-9-]` segments around the required leading + trailing
+// alnum look like nested quantifiers but each reads from a single
+// bounded class — worst-case backtracking is linear. Exported as the
+// single source of truth so the catalog reader + installer agree by
+// construction instead of duplicating the literal.
+// eslint-disable-next-line security/detect-unsafe-regex -- non-overlapping classes
+const SAFE_REPO_ID_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+
+/** True when `value` has the shape `deriveRepoId` produces. */
+export function isSafeRepoId(value: string): boolean {
+  return SAFE_REPO_ID_RE.test(value);
+}
+
+/** Launder a (possibly user-supplied) repo id into a safe directory
+ *  leaf, or `null` if it fails the shape check or isn't a basename.
+ *  The `path.basename` round-trip is CodeQL's recognised
+ *  `js/path-injection` sanitiser — callers MUST compose paths from
+ *  the returned value (not the raw input) so the taint flow ends
+ *  here. A regex `.test()` alone is NOT recognised as a sanitiser. */
+export function safeRepoId(raw: string): string | null {
+  if (!SAFE_REPO_ID_RE.test(raw)) return null;
+  const basename = path.basename(raw);
+  return basename === raw ? basename : null;
+}
+
+/** Launder a skill-folder leaf name (the directory directly under a
+ *  repo / subpath that contains `SKILL.md`). This is the SINGLE rule
+ *  shared by install-time discovery AND read/star addressing — if the
+ *  two diverged (as they did: install accepted `v1.2` but the read
+ *  side's stricter regex dropped it), an install could succeed yet be
+ *  invisible/unaddressable in list/preview/star.
+ *
+ *  Permissive by design (mirrors what install discovery accepts: any
+ *  non-hidden one-level dir) but still traversal-safe: rejects empty,
+ *  `.`/`..`, leading-dot (hidden), separators, NUL, and anything that
+ *  isn't its own `path.basename` (CodeQL `js/path-injection`
+ *  sanitiser). Dots elsewhere (`v1.2`) are allowed. */
+export function safeSkillFolder(raw: string): string | null {
+  if (raw.length === 0 || raw === "." || raw === "..") return null;
+  if (raw.startsWith(".")) return null;
+  if (raw.includes("/") || raw.includes("\\") || raw.includes("\0")) return null;
+  const basename = path.basename(raw);
+  return basename === raw ? basename : null;
+}
+
+// A single safe path segment: alnum plus `.`, `-`, `_`. `..` is
+// rejected explicitly by the caller before this is consulted, so the
+// dot allowance can't yield a traversal token.
+const SUBPATH_SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
+
+/** Sanitise a caller-supplied repo subpath (`POST /external/repos`
+ *  body). The raw value flows into `path.join(cacheDir, subpath)` and
+ *  into the git sparse-checkout pattern, so an un-validated `../../etc`
+ *  / `\0` / newline would escape the scratch dir or inject extra
+ *  sparse patterns. Returns a normalised `a/b/c` string (no leading or
+ *  trailing slash, no `.`/`..`/empty segments) or `null` on rejection. */
+export function sanitiseSubpath(raw: string): string | null {
+  if (raw.length === 0) return null;
+  if (raw.includes("\0") || raw.includes("\\") || raw.includes("\n") || raw.includes("\r")) return null;
+  if (raw.startsWith("/")) return null;
+  const safe: string[] = [];
+  for (const segment of raw.split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === ".." || !SUBPATH_SEGMENT_PATTERN.test(segment)) return null;
+    safe.push(segment);
+  }
+  if (safe.length === 0) return null;
+  return safe.join("/");
+}