skillcaddy 0.27.0

package/lib/sourceGitUrl.js

@@ -0,0 +1,170 @@
+import { SourceAcquisitionError } from './sourceAcquisitionError.js';
+import { sanitizeGitRemote, validateSourceId } from './sourceRecord.js';
+import { isGitHubBlobSkillFileInput } from './sourceRemoteFilePolicy.js';
+
+export function isGitSourceInput(input) {
+  if (typeof input !== 'string') return false;
+  const trimmed = input.trim();
+  return isSshGitInput(trimmed) || /^https:\/\//i.test(trimmed);
+}
+
+export function isDefiniteGitSourceInput(input) {
+  if (typeof input !== 'string') return false;
+  const trimmed = input.trim();
+  if (isSshGitInput(trimmed)) return true;
+  if (isGitHubBlobSkillFileInput(trimmed)) return false;
+  let url;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== 'https:') return false;
+  if (/\.git\/?$/i.test(url.pathname)) return true;
+  return ['github.com', 'www.github.com'].includes(url.hostname.toLowerCase()) &&
+    url.pathname.split('/').filter(Boolean).length >= 2;
+}
+
+function isSshGitInput(input) {
+  if (
+    /^ssh:\/\//i.test(input) ||
+    !input.includes('://') &&
+      /^(?:[^@\s]+@)?[^:/\s]+:[^/\s][^\s]*$/.test(input)
+  ) {
+    return true;
+  }
+  return false;
+}
+
+export function parseGitSourceRequest(request) {
+  if (!request || typeof request.input !== 'string' || !request.input.trim()) {
+    throw new Error('Source add requires request.input');
+  }
+  if (request.name !== undefined || request.namespace !== undefined) {
+    throw identityError('Git source identity is derived from its repository owner and name');
+  }
+
+  const input = request.input.trim();
+  if (input.includes('://')) return parseGitUrl(input);
+  return parseScpGitUrl(input);
+}
+
+export function canonicalGitRepositoryLocation(remote) {
+  if (remote.includes('://')) {
+    const url = new URL(remote);
+    return `${url.hostname.toLowerCase()}/${normalizeRepositoryPath(url.pathname)}`;
+  }
+  const separator = remote.indexOf(':');
+  const host = remote.slice(0, separator).replace(/^.*@/, '').toLowerCase();
+  return `${host}/${normalizeRepositoryPath(remote.slice(separator + 1))}`;
+}
+
+function parseGitUrl(input) {
+  let url;
+  try {
+    url = new URL(input);
+  } catch {
+    throw identityError('Invalid Git source URL');
+  }
+  if (!['https:', 'ssh:'].includes(url.protocol)) {
+    throw identityError('Git source URL must use HTTPS or SSH');
+  }
+
+  const segments = decodePathSegments(url.pathname);
+  if (
+    url.protocol === 'https:' &&
+    ['github.com', 'www.github.com'].includes(url.hostname.toLowerCase()) &&
+    segments[2] === 'tree'
+  ) {
+    if (segments.length < 4) {
+      throw identityError('GitHub tree URL must include a branch');
+    }
+    const [owner, rawRepository, , ...treeSegments] = segments;
+    const repository = stripGitSuffix(rawRepository);
+    const repositoryRemote = `https://github.com/${owner}/${repository}.git`;
+    return validateParsedGitSource({
+      owner,
+      repository,
+      cloneRemote: repositoryRemote,
+      displayRemote: repositoryRemote,
+      treeSegments
+    });
+  }
+
+  if (segments.length < 2) {
+    throw identityError('Git source URL must identify a repository owner and name');
+  }
+  const owner = segments.at(-2);
+  const repository = stripGitSuffix(segments.at(-1));
+  const cloneUrl = new URL(url);
+  cloneUrl.search = '';
+  cloneUrl.hash = '';
+  if (cloneUrl.protocol === 'https:') {
+    cloneUrl.username = '';
+    cloneUrl.password = '';
+  } else {
+    cloneUrl.password = '';
+  }
+  return validateParsedGitSource({
+    owner,
+    repository,
+    cloneRemote: cloneUrl.toString(),
+    displayRemote: sanitizeGitRemote(cloneUrl.toString())
+  });
+}
+
+function parseScpGitUrl(input) {
+  if (!/^(?:[^@\s]+@)?[^:/\s]+:[^?#\s]+(?:[?#].*)?$/.test(input)) {
+    throw identityError('Invalid SSH Git source URL');
+  }
+  const withoutSensitiveSuffix = input.replace(/[?#].*$/, '');
+  const repositoryPath = withoutSensitiveSuffix.slice(withoutSensitiveSuffix.indexOf(':') + 1);
+  const segments = decodePathSegments(repositoryPath);
+  if (segments.length < 2) {
+    throw identityError('Git source URL must identify a repository owner and name');
+  }
+  return validateParsedGitSource({
+    owner: segments.at(-2),
+    repository: stripGitSuffix(segments.at(-1)),
+    cloneRemote: withoutSensitiveSuffix,
+    displayRemote: sanitizeGitRemote(withoutSensitiveSuffix)
+  });
+}
+
+function validateParsedGitSource(parsed) {
+  const sourceId = `github/${parsed.owner}/${parsed.repository}`;
+  try {
+    validateSourceId(sourceId);
+  } catch {
+    throw identityError('Git repository owner and name must form a safe source identity');
+  }
+  return { ...parsed, sourceId };
+}
+
+function decodePathSegments(pathname) {
+  try {
+    return pathname
+      .split('/')
+      .filter(Boolean)
+      .map((segment) => decodeURIComponent(segment));
+  } catch {
+    throw identityError('Git source URL contains invalid path encoding');
+  }
+}
+
+function stripGitSuffix(repository) {
+  const normalized = repository.replace(/\.git$/i, '');
+  if (!normalized) throw identityError('Git source URL has no repository name');
+  return normalized;
+}
+
+function normalizeRepositoryPath(repositoryPath) {
+  return repositoryPath
+    .replace(/^\/+/, '')
+    .replace(/\/+$/, '')
+    .replace(/\.git$/i, '');
+}
+
+function identityError(message) {
+  return new SourceAcquisitionError('unresolved-identity', message, 3);
+}

package/lib/sourceHttp.js

@@ -0,0 +1,302 @@
+import { createWriteStream } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import http from 'node:http';
+import https from 'node:https';
+import { pipeline } from 'node:stream/promises';
+import { getDomain } from 'tldts';
+import { SourceAcquisitionError } from './sourceAcquisitionError.js';
+import {
+  isRemoteSkillFilePathInput,
+  validateRemoteSkillFileUrl
+} from './sourceRemoteFilePolicy.js';
+
+const DEFAULT_HTTP_LIMITS = {
+  maxDownloadBytes: 100 * 1024 * 1024,
+  maxRedirects: 5,
+  connectionTimeoutMs: 15_000,
+  completeTimeoutMs: 120_000
+};
+const DEFAULT_REMOTE_SKILL_FILE_LIMITS = {
+  ...DEFAULT_HTTP_LIMITS,
+  maxDownloadBytes: 1024 * 1024
+};
+
+export function isRemoteArchiveInput(input) {
+  if (typeof input !== 'string') return false;
+  return /^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(input.trim());
+}
+
+export function isRemoteSkillFileInput(input) {
+  return isRemoteSkillFilePathInput(input);
+}
+
+export function parseRemoteSkillFileRequest(request) {
+  if (!request || typeof request.input !== 'string' || !request.input.trim()) {
+    throw new Error('Source add requires request.input');
+  }
+  if (typeof request.name !== 'string' || !request.name) {
+    throw identityError('Remote file source requires an explicit non-empty name');
+  }
+  if (request.namespace !== undefined) {
+    throw identityError('Remote file source does not accept a namespace');
+  }
+  const parsedInput = parseRemoteSkillFileInput(request.input);
+  return {
+    ...parsedInput,
+    name: request.name
+  };
+}
+
+export function parseRemoteSkillFileInput(input) {
+  if (typeof input !== 'string' || !input.trim()) {
+    throw new Error('Remote file source input is required');
+  }
+  let parsed;
+  try {
+    parsed = validateRemoteSkillFileUrl(input, { allowFragment: true });
+  } catch (error) {
+    throw downloadError(error.message);
+  }
+  return {
+    input: parsed.display,
+    ...parsed
+  };
+}
+
+export function parseRemoteArchiveRequest(request) {
+  if (!request || typeof request.input !== 'string' || !request.input.trim()) {
+    throw new Error('Source add requires request.input');
+  }
+  const parsedInput = parseRemoteArchiveInput(request.input);
+  const url = parsedInput.url;
+  const name = request.name === undefined ? inferArchiveName(url) : request.name;
+  if (typeof name !== 'string' || !name) {
+    throw identityError('Remote Archive name must be a non-empty identity segment');
+  }
+  if (
+    request.namespace !== undefined &&
+    (typeof request.namespace !== 'string' || !request.namespace)
+  ) {
+    throw identityError('Remote Archive namespace must be a non-empty identity segment');
+  }
+  return {
+    ...parsedInput,
+    name,
+    namespace: request.namespace,
+    registrableDomain: getDomain(url.hostname, { allowPrivateDomains: true }) ||
+      url.hostname.toLowerCase()
+  };
+}
+
+export function parseRemoteArchiveInput(input) {
+  if (typeof input !== 'string' || !input.trim()) {
+    throw new Error('Remote Archive input is required');
+  }
+  const url = requireHttpUrl(input);
+  return {
+    input: input.trim(),
+    url,
+    display: sanitizeRemoteArchiveUrl(url),
+    protocol: url.protocol.slice(0, -1)
+  };
+}
+
+export async function downloadRemoteArchive(input, destination, options = {}) {
+  return downloadRemoteResource(input, destination, {
+    ...options,
+    defaultLimits: DEFAULT_HTTP_LIMITS,
+    resourceLabel: 'Remote ZIP'
+  });
+}
+
+export async function downloadRemoteSkillFile(input, destination, options = {}) {
+  return downloadRemoteResource(input, destination, {
+    ...options,
+    defaultLimits: DEFAULT_REMOTE_SKILL_FILE_LIMITS,
+    resourceLabel: 'Remote SKILL.md',
+    validateUrl: (url) => parseRemoteSkillFileInput(url.toString())
+  });
+}
+
+async function downloadRemoteResource(input, destination, options) {
+  const limits = { ...options.defaultLimits, ...options.limits };
+  const resourceLabel = options.resourceLabel;
+  const controller = new AbortController();
+  const completeTimer = setTimeout(() => {
+    controller.abort(downloadError(
+      `${resourceLabel} complete-download timeout exceeded`
+    ));
+  }, limits.completeTimeoutMs);
+
+  try {
+    const response = await followRedirects(
+      requireHttpUrl(input),
+      limits,
+      options.lookup,
+      controller.signal,
+      options.validateUrl,
+      resourceLabel
+    );
+    await writeResponse(
+      response,
+      destination,
+      limits.maxDownloadBytes,
+      resourceLabel
+    );
+  } catch (error) {
+    await rm(destination, { force: true });
+    if (error instanceof SourceAcquisitionError) throw error;
+    if (
+      controller.signal.aborted &&
+      controller.signal.reason instanceof SourceAcquisitionError
+    ) {
+      throw controller.signal.reason;
+    }
+    if (error.cause instanceof SourceAcquisitionError) throw error.cause;
+    throw downloadError(`${resourceLabel} download was truncated or interrupted`);
+  } finally {
+    clearTimeout(completeTimer);
+  }
+}
+
+async function followRedirects(
+  url,
+  limits,
+  lookup,
+  signal,
+  validateUrl,
+  resourceLabel,
+  redirectCount = 0
+) {
+  if (validateUrl) validateUrl(url);
+  const response = await requestUrl(url, {
+    connectionTimeoutMs: limits.connectionTimeoutMs,
+    lookup,
+    signal,
+    resourceLabel
+  });
+  if (![301, 302, 303, 307, 308].includes(response.statusCode)) {
+    if (response.statusCode < 200 || response.statusCode >= 300) {
+      response.resume();
+      throw downloadError(
+        `${resourceLabel} request failed with HTTP ${response.statusCode}`
+      );
+    }
+    return response;
+  }
+
+  response.resume();
+  if (redirectCount >= limits.maxRedirects) {
+    throw downloadError(
+      `${resourceLabel} exceeded ${limits.maxRedirects} redirects`
+    );
+  }
+  const location = response.headers.location;
+  if (!location) {
+    throw downloadError(`${resourceLabel} redirect is missing Location`);
+  }
+  let next;
+  try {
+    next = new URL(location, url);
+  } catch {
+    throw downloadError(`${resourceLabel} redirect has an invalid Location`);
+  }
+  if (next.protocol !== url.protocol) {
+    throw downloadError(`${resourceLabel} redirect changed protocol`);
+  }
+  return followRedirects(
+    next,
+    limits,
+    lookup,
+    signal,
+    validateUrl,
+    resourceLabel,
+    redirectCount + 1
+  );
+}
+
+function requestUrl(url, {
+  connectionTimeoutMs,
+  lookup,
+  signal,
+  resourceLabel
+}) {
+  const client = url.protocol === 'http:' ? http : https;
+  return new Promise((resolve, reject) => {
+    const request = client.get(url, { lookup, signal }, resolve);
+    let connectionTimer;
+    request.once('socket', (socket) => {
+      if (!socket.connecting) return;
+      connectionTimer = setTimeout(() => {
+        request.destroy(downloadError(
+          `${resourceLabel} connection timeout exceeded`
+        ));
+      }, connectionTimeoutMs);
+      const event = url.protocol === 'https:' ? 'secureConnect' : 'connect';
+      socket.once(event, () => clearTimeout(connectionTimer));
+    });
+    request.once('error', reject);
+    request.once('close', () => clearTimeout(connectionTimer));
+  });
+}
+
+async function writeResponse(
+  response,
+  destination,
+  maxDownloadBytes,
+  resourceLabel
+) {
+  let downloadedBytes = 0;
+  response.on('data', (chunk) => {
+    downloadedBytes += chunk.length;
+    if (downloadedBytes > maxDownloadBytes) {
+      response.destroy(downloadError(
+        `${resourceLabel} exceeds the ${maxDownloadBytes}-byte download limit`
+      ));
+    }
+  });
+  await pipeline(response, createWriteStream(destination, { flags: 'wx' }));
+  if (!response.complete) {
+    throw downloadError(`${resourceLabel} download was truncated`);
+  }
+}
+
+function requireHttpUrl(input, inputLabel = 'Remote Archive') {
+  let url;
+  try {
+    url = new URL(input);
+  } catch {
+    throw downloadError(`${inputLabel} input must be a valid HTTP(S) URL`);
+  }
+  if (!['http:', 'https:'].includes(url.protocol)) {
+    throw downloadError(`${inputLabel} input must use HTTP or HTTPS`);
+  }
+  return url;
+}
+
+function sanitizeRemoteArchiveUrl(url) {
+  const sanitized = new URL(url);
+  sanitized.username = '';
+  sanitized.password = '';
+  sanitized.search = '';
+  sanitized.hash = '';
+  return sanitized.toString();
+}
+
+function inferArchiveName(url) {
+  let basename;
+  try {
+    basename = decodeURIComponent(url.pathname.split('/').filter(Boolean).at(-1) || '');
+  } catch {
+    throw identityError('Remote Archive URL contains invalid path encoding');
+  }
+  return basename.replace(/\.zip$/i, '');
+}
+
+function identityError(message) {
+  return new SourceAcquisitionError('unresolved-identity', message, 3);
+}
+
+function downloadError(message) {
+  return new SourceAcquisitionError('download-failure', message);
+}

package/lib/sourceLocal.js

@@ -0,0 +1,200 @@
+import { constants, createReadStream, createWriteStream } from 'node:fs';
+import {
+  lstat,
+  mkdir,
+  mkdtemp,
+  open,
+  readlink,
+  realpath,
+  readdir,
+  rm,
+  symlink
+} from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { SourceAcquisitionError } from './sourceAcquisitionError.js';
+import { extractZip, hasZipSignature } from './sourceArchive.js';
+import { isPathInsideOrEqual } from './sourcePath.js';
+import { checksumDirectory, sourcePathExists } from './sourceTree.js';
+import { validateStagedSource } from './sourceValidation.js';
+
+export async function inspectLocalInput(inputPath, options = {}) {
+  const input = await classifyLocalInput(inputPath);
+  if (input.type === 'local-directory') {
+    await validateLocalDirectory(inputPath);
+    return buildPreparedInput(input, inputPath);
+  }
+
+  const temporaryRoot = await mkdtemp(path.join(tmpdir(), 'skillcaddy-zip-plan-'));
+  try {
+    const extractedRoot = path.join(temporaryRoot, 'content');
+    await extractZip(inputPath, extractedRoot, options.archiveLimits);
+    const contentRoot = await unwrapArchiveRoot(extractedRoot);
+    return await buildPreparedInput(input, contentRoot);
+  } finally {
+    await rm(temporaryRoot, { recursive: true, force: true });
+  }
+}
+
+export async function stageLocalInput(inputPath, stagingRoot, options = {}) {
+  const input = await classifyLocalInput(inputPath);
+  const contentRoot = path.join(stagingRoot, 'content');
+  if (input.type === 'local-directory') {
+    await validateLocalDirectory(inputPath);
+    await copyLocalDirectory(inputPath, contentRoot);
+    await validateLocalDirectory(contentRoot);
+    return buildPreparedInput(input, contentRoot);
+  }
+
+  await extractZip(inputPath, contentRoot, options.archiveLimits);
+  return buildPreparedInput(input, await unwrapArchiveRoot(contentRoot));
+}
+
+async function buildPreparedInput(input, contentRoot) {
+  const validation = await validateStagedSource(contentRoot);
+  return {
+    ...input,
+    contentRoot,
+    integrity: {
+      algorithm: 'sha256',
+      value: await checksumDirectory(contentRoot)
+    },
+    ...validation
+  };
+}
+
+async function classifyLocalInput(inputPath) {
+  let stat;
+  try {
+    stat = await lstat(inputPath);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new SourceAcquisitionError(
+        'invalid-input',
+        `Local input does not exist: ${path.basename(inputPath)}`
+      );
+    }
+    throw error;
+  }
+
+  const basename = path.basename(path.resolve(inputPath));
+  if (stat.isDirectory()) {
+    return { type: 'local-directory', basename, defaultName: basename };
+  }
+  if (!stat.isFile()) {
+    throw new SourceAcquisitionError('invalid-input', 'Local input must be a directory or ZIP file');
+  }
+  if (!(await hasZipSignature(inputPath))) {
+    throw new SourceAcquisitionError('invalid-input', 'Local file does not have a ZIP signature');
+  }
+  return {
+    type: 'local-zip',
+    basename,
+    defaultName: basename.replace(/\.zip$/i, '') || basename
+  };
+}
+
+async function validateLocalDirectory(sourceRoot) {
+  const resolvedRoot = await realpath(sourceRoot);
+
+  async function walk(directory, relativeDirectory = '') {
+    const entries = await readdir(directory, { withFileTypes: true });
+    for (const entry of entries) {
+      const entryPath = path.join(directory, entry.name);
+      const relativePath = path.posix.join(relativeDirectory, entry.name);
+      if (entry.isDirectory()) {
+        await walk(entryPath, relativePath);
+      } else if (entry.isSymbolicLink()) {
+        await validateLocalSymlink(resolvedRoot, entryPath, relativePath);
+      } else if (!entry.isFile()) {
+        throw new SourceAcquisitionError(
+          'source-safety',
+          `Unsupported local source entry: ${relativePath}`
+        );
+      }
+    }
+  }
+
+  await walk(sourceRoot);
+}
+
+async function validateLocalSymlink(resolvedRoot, entryPath, relativePath) {
+  const target = await readlink(entryPath);
+  if (path.isAbsolute(target)) {
+    throw new SourceAcquisitionError(
+      'source-safety',
+      `Absolute local symlink is not allowed: ${relativePath}`
+    );
+  }
+  let resolvedTarget;
+  try {
+    resolvedTarget = await realpath(entryPath);
+  } catch {
+    throw new SourceAcquisitionError(
+      'source-safety',
+      `Broken local symlink is not allowed: ${relativePath}`
+    );
+  }
+  if (!isPathInsideOrEqual(resolvedRoot, resolvedTarget)) {
+    throw new SourceAcquisitionError(
+      'source-safety',
+      `Escaping local symlink is not allowed: ${relativePath}`
+    );
+  }
+}
+
+async function copyLocalDirectory(sourceRoot, destinationRoot) {
+  await mkdir(destinationRoot, { recursive: true });
+
+  async function copyDirectory(sourceDirectory, destinationDirectory) {
+    const entries = await readdir(sourceDirectory, { withFileTypes: true });
+    for (const entry of entries) {
+      const sourcePath = path.join(sourceDirectory, entry.name);
+      const destinationPath = path.join(destinationDirectory, entry.name);
+      if (entry.isDirectory()) {
+        await mkdir(destinationPath);
+        await copyDirectory(sourcePath, destinationPath);
+      } else if (entry.isSymbolicLink()) {
+        await symlink(await readlink(sourcePath), destinationPath);
+      } else if (entry.isFile()) {
+        await copyRegularFile(sourcePath, destinationPath);
+      } else {
+        throw new SourceAcquisitionError(
+          'source-safety',
+          `Unsupported local source entry: ${path.relative(sourceRoot, sourcePath)}`
+        );
+      }
+    }
+  }
+
+  await copyDirectory(sourceRoot, destinationRoot);
+}
+
+async function copyRegularFile(sourcePath, destinationPath) {
+  const handle = await open(sourcePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile()) {
+      throw new SourceAcquisitionError('source-safety', 'Local source changed during copying');
+    }
+    await pipeline(
+      createReadStream(null, { fd: handle.fd, autoClose: false }),
+      createWriteStream(destinationPath, { flags: 'wx', mode: stat.mode & 0o777 })
+    );
+  } finally {
+    await handle.close();
+  }
+}
+
+async function unwrapArchiveRoot(extractedRoot) {
+  let currentRoot = extractedRoot;
+  while (true) {
+    const entries = await readdir(currentRoot, { withFileTypes: true });
+    if (entries.length !== 1 || !entries[0].isDirectory()) return currentRoot;
+    const directSkill = path.join(currentRoot, 'SKILL.md');
+    const skillsDirectory = path.join(currentRoot, 'skills');
+    if (await sourcePathExists(directSkill) || await sourcePathExists(skillsDirectory)) return currentRoot;
+    currentRoot = path.join(currentRoot, entries[0].name);
+  }
+}