skillcaddy 0.27.0

package/lib/sourceRecord.js

@@ -0,0 +1,295 @@
+import path from 'node:path';
+import { SOURCE_FOLDERS } from './sourcePolicy.js';
+import { validateRemoteSkillFileUrl } from './sourceRemoteFilePolicy.js';
+
+const SUPPORTED_SCHEMA_VERSION = 1;
+const SOURCE_BUCKET_BY_TYPE = {
+  git: 'github',
+  archive: 'official',
+  'remote-file': 'official',
+  local: 'personal'
+};
+const SOURCE_TYPES = new Set([...Object.keys(SOURCE_BUCKET_BY_TYPE), 'legacy-local']);
+const SOURCE_SEGMENT = /^(?:\.?[A-Za-z0-9])(?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
+const SHA256 = /^[a-f0-9]{64}$/i;
+
+export function validateSourceId(sourceId) {
+  if (typeof sourceId !== 'string') throw new Error('Invalid sourceId');
+  const segments = sourceId.split('/');
+  if (
+    segments.length < 2 ||
+    !SOURCE_FOLDERS.includes(segments[0]) ||
+    segments.some((segment) => !SOURCE_SEGMENT.test(segment))
+  ) {
+    throw new Error(`Invalid sourceId: ${sourceId}`);
+  }
+  return sourceId;
+}
+
+export function validateSourceRecord(rootDir, record, expectedSourceId) {
+  if (!record || typeof record !== 'object' || Array.isArray(record)) {
+    throw new Error('Source record must be an object');
+  }
+  if (record.schemaVersion !== SUPPORTED_SCHEMA_VERSION) {
+    throw new Error(`Unsupported source record schemaVersion: ${record.schemaVersion}`);
+  }
+
+  const sourceId = validateSourceId(record.sourceId);
+  if (expectedSourceId && sourceId !== expectedSourceId) {
+    throw new Error(`Source record path does not match sourceId: ${sourceId}`);
+  }
+  if (!SOURCE_FOLDERS.includes(record.bucket) || !sourceId.startsWith(`${record.bucket}/`)) {
+    throw new Error(`Invalid source bucket for ${sourceId}`);
+  }
+  if (!SOURCE_TYPES.has(record.type)) {
+    throw new Error(`Unsupported source type: ${record.type}`);
+  }
+  if (SOURCE_BUCKET_BY_TYPE[record.type] && SOURCE_BUCKET_BY_TYPE[record.type] !== record.bucket) {
+    throw new Error(`Source type ${record.type} must use the ${SOURCE_BUCKET_BY_TYPE[record.type]} bucket`);
+  }
+
+  const integrity = validateIntegrity(record.integrity);
+  const skills = validateSkillPaths(record.skills);
+  const installPath = validateInstallPath(rootDir, record.installPath);
+  if (record.type === 'remote-file' && !integrity) {
+    throw new Error('Remote file source record requires integrity');
+  }
+  if (
+    record.type === 'remote-file' &&
+    (skills.length !== 1 || skills[0] !== '.')
+  ) {
+    throw new Error('Remote file source record requires exactly the root skill');
+  }
+  if (
+    record.type === 'remote-file' &&
+    (sourceId.split('/').length !== 2 || installPath !== sourceId)
+  ) {
+    throw new Error(
+      'Remote file source install path must match its official source identity'
+    );
+  }
+  return {
+    schemaVersion: SUPPORTED_SCHEMA_VERSION,
+    sourceId,
+    bucket: record.bucket,
+    type: record.type,
+    installPath,
+    origin: validateOrigin(record.type, record.origin),
+    ...(record.focus === undefined ? {} : { focus: validateSourceFocus(record.type, record.focus) }),
+    ...(integrity ? { integrity } : {}),
+    skills
+  };
+}
+
+function validateSourceFocus(type, focus) {
+  if (type !== 'git' || !focus || typeof focus !== 'object' || Array.isArray(focus)) {
+    throw new Error('Source focus is only valid for Git sources');
+  }
+  const ref = validateGitRef(focus.ref);
+  if (!ref) throw new Error('Git source focus requires a ref');
+  const allowedKeys = new Set(['ref', 'path']);
+  if (Object.keys(focus).some((key) => !allowedKeys.has(key))) {
+    throw new Error('Git source focus contains unsupported fields');
+  }
+  if (focus.path === undefined) return { ref };
+  if (
+    typeof focus.path !== 'string' ||
+    !focus.path ||
+    path.posix.isAbsolute(focus.path) ||
+    path.posix.normalize(focus.path) !== focus.path ||
+    focus.path.includes('\\') ||
+    hasControlCharacters(focus.path) ||
+    focus.path.split('/').some((segment) => !segment || segment === '.' || segment === '..')
+  ) {
+    throw new Error('Invalid Git source focus path');
+  }
+  return { ref, path: focus.path };
+}
+
+function validateInstallPath(rootDir, installPath) {
+  if (
+    typeof installPath !== 'string' ||
+    path.isAbsolute(installPath) ||
+    installPath.includes('\\') ||
+    hasControlCharacters(installPath)
+  ) {
+    throw new Error('installPath must stay inside the central-library root');
+  }
+
+  const normalized = path.posix.normalize(installPath);
+  const segments = normalized.split('/');
+  const resolvedRoot = path.resolve(rootDir);
+  const relative = path.relative(resolvedRoot, path.resolve(resolvedRoot, normalized));
+  if (
+    normalized !== installPath ||
+    segments.length < 2 ||
+    !SOURCE_FOLDERS.includes(segments[0]) ||
+    segments.some((segment) => !segment || segment === '.' || segment === '..') ||
+    !relative ||
+    relative.startsWith('..') ||
+    path.isAbsolute(relative)
+  ) {
+    throw new Error('installPath must stay inside the central-library root');
+  }
+  return normalized;
+}
+
+function validateOrigin(type, origin) {
+  if (!origin || typeof origin !== 'object' || Array.isArray(origin)) {
+    throw new Error(`Invalid origin for source type: ${type}`);
+  }
+
+  if (type === 'git') {
+    if (origin.kind !== 'git' || typeof origin.remote !== 'string' || !origin.remote.trim()) {
+      throw new Error('Git source origin requires a remote');
+    }
+    return compactObject({
+      kind: 'git',
+      remote: sanitizeGitRemote(origin.remote),
+      ref: validateGitRef(origin.ref),
+      commit: optionalCommit(origin.commit)
+    });
+  }
+
+  if (type === 'remote-file') {
+    if (!['http', 'https'].includes(origin.kind) || typeof origin.display !== 'string') {
+      throw new Error('Remote file source origin requires a stable HTTP(S) URL');
+    }
+    let parsed;
+    try {
+      parsed = validateRemoteSkillFileUrl(origin.display);
+    } catch (error) {
+      throw new Error(`Remote file source origin is invalid: ${error.message}`);
+    }
+    if (parsed.protocol !== origin.kind) {
+      throw new Error('Remote file source origin kind must match its URL protocol');
+    }
+    return { kind: origin.kind, display: parsed.display };
+  }
+
+  if (type === 'archive') {
+    if (!['http', 'https'].includes(origin.kind) || typeof origin.display !== 'string' || !origin.display.trim()) {
+      throw new Error('Archive source origin requires an HTTP(S) display URL');
+    }
+    const display = sanitizeUrl(origin.display, [`${origin.kind}:`]);
+    return { kind: origin.kind, display };
+  }
+
+  if (type === 'local') {
+    if (
+      origin.kind !== 'local' ||
+      typeof origin.name !== 'string' ||
+      !origin.name ||
+      path.basename(origin.name) !== origin.name ||
+      hasControlCharacters(origin.name)
+    ) {
+      throw new Error('Local source origin requires a basename');
+    }
+    return { kind: 'local', name: origin.name };
+  }
+
+  if (origin.kind !== 'unknown') {
+    throw new Error('Legacy Local source origin must be unknown');
+  }
+  return { kind: 'unknown' };
+}
+
+function validateIntegrity(integrity) {
+  if (integrity === undefined) return null;
+  if (
+    !integrity ||
+    typeof integrity !== 'object' ||
+    integrity.algorithm !== 'sha256' ||
+    typeof integrity.value !== 'string' ||
+    !SHA256.test(integrity.value)
+  ) {
+    throw new Error('Invalid source integrity');
+  }
+  return { algorithm: 'sha256', value: integrity.value.toLowerCase() };
+}
+
+function validateSkillPaths(skills) {
+  if (!Array.isArray(skills)) throw new Error('Source record skills must be an array');
+  const validated = skills.map((skillPath) => {
+    if (
+      typeof skillPath !== 'string' ||
+      !skillPath ||
+      path.posix.normalize(skillPath) !== skillPath ||
+      path.posix.isAbsolute(skillPath) ||
+      skillPath.includes('\\') ||
+      hasControlCharacters(skillPath) ||
+      skillPath !== '.' &&
+        skillPath.split('/').some((segment) => !segment || segment === '.' || segment === '..')
+    ) {
+      throw new Error(`Invalid discovered skill path: ${skillPath}`);
+    }
+    return skillPath;
+  });
+  if (new Set(validated).size !== validated.length) {
+    throw new Error('Source record contains duplicate skill paths');
+  }
+  return validated;
+}
+
+export function sanitizeGitRemote(remote) {
+  const trimmed = remote.trim();
+  if (hasControlCharacters(trimmed)) throw new Error('Invalid Git source origin');
+  if (trimmed.includes('://')) return sanitizeUrl(trimmed, ['https:', 'ssh:']);
+  if (!/^(?:[^@\s]+@)?[^:/\s]+:[^?#\s]+(?:[?#].*)?$/.test(trimmed)) {
+    throw new Error('Invalid Git source origin');
+  }
+  return trimmed
+    .replace(/^[^@\s]+@(?=[^:\s]+:)/, '')
+    .replace(/[?#].*$/, '');
+}
+
+function sanitizeUrl(value, protocols) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error('Invalid source origin URL');
+  }
+  if (!protocols.includes(url.protocol)) throw new Error('Invalid source origin URL');
+  url.username = '';
+  url.password = '';
+  url.search = '';
+  url.hash = '';
+  return url.toString();
+}
+
+function validateGitRef(value) {
+  if (value === undefined) return undefined;
+  if (
+    typeof value !== 'string' ||
+    !value ||
+    hasControlCharacters(value) ||
+    /[\s~^:?*[\]\\]/.test(value) ||
+    value.includes('..') ||
+    value.includes('@{') ||
+    value.includes('//') ||
+    value.startsWith('/') ||
+    value.endsWith('/') ||
+    value.endsWith('.') ||
+    value.split('/').some((segment) => segment.startsWith('.') || segment.endsWith('.lock'))
+  ) {
+    throw new Error('Invalid origin.ref');
+  }
+  return value;
+}
+
+function optionalCommit(value) {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string' || !/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/i.test(value)) {
+    throw new Error('Invalid origin.commit');
+  }
+  return value.toLowerCase();
+}
+
+function hasControlCharacters(value) {
+  return /[\u0000-\u001F\u007F]/.test(value);
+}
+
+function compactObject(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}

package/lib/sourceRegistry.js

@@ -0,0 +1,155 @@
+import { randomUUID } from 'node:crypto';
+import {
+  lstat,
+  link,
+  mkdir,
+  readFile,
+  readdir,
+  realpath,
+  rename,
+  rm,
+  writeFile
+} from 'node:fs/promises';
+import path from 'node:path';
+import { isPathInsideOrEqual } from './sourcePath.js';
+import { validateSourceId, validateSourceRecord } from './sourceRecord.js';
+
+export { validateSourceId };
+
+export async function readSourceRecords(rootDir) {
+  const registryRoot = path.join(path.resolve(rootDir), '.skillcaddy', 'sources');
+  const files = await findJsonFiles(registryRoot);
+  const records = [];
+
+  for (const filePath of files) {
+    const expectedSourceId = path.relative(registryRoot, filePath).slice(0, -'.json'.length).split(path.sep).join('/');
+    const record = await readRecord(filePath);
+    const validated = validateSourceRecord(rootDir, record, expectedSourceId);
+    await assertExistingPathInsideRoot(
+      rootDir,
+      path.resolve(rootDir, validated.installPath),
+      'installPath resolves outside the central-library root'
+    );
+    records.push(validated);
+  }
+
+  return records.sort((left, right) => left.sourceId.localeCompare(right.sourceId));
+}
+
+export async function writeSourceRecord(rootDir, record) {
+  return publishSourceRecord(rootDir, record, replaceRecord);
+}
+
+export async function createSourceRecord(rootDir, record) {
+  return publishSourceRecord(rootDir, record, createRecord);
+}
+
+async function publishSourceRecord(rootDir, record, publish) {
+  const staged = await stageSourceRecord(rootDir, record);
+  let published = false;
+  try {
+    await publish(staged.temporaryPath, staged.targetPath);
+    published = true;
+  } finally {
+    try {
+      await discardStagedSourceRecord(staged);
+    } catch (error) {
+      if (!published) throw error;
+    }
+  }
+  return staged.record;
+}
+
+export async function stageSourceRecord(rootDir, record) {
+  const validated = validateSourceRecord(rootDir, record);
+  await assertExistingPathInsideRoot(
+    rootDir,
+    path.resolve(rootDir, validated.installPath),
+    'installPath resolves outside the central-library root'
+  );
+
+  const registryRoot = path.join(path.resolve(rootDir), '.skillcaddy', 'sources');
+  const targetPath = path.join(registryRoot, ...validated.sourceId.split('/')) + '.json';
+  await assertExistingPathInsideRoot(
+    rootDir,
+    targetPath,
+    'Source registry path resolves outside the central-library root'
+  );
+  await mkdir(path.dirname(targetPath), { recursive: true });
+
+  const temporaryPath = `${targetPath}.${randomUUID()}.tmp`;
+  await writeFile(temporaryPath, `${JSON.stringify(validated, null, 2)}\n`, { flag: 'wx' });
+  return {
+    record: validated,
+    targetPath,
+    temporaryPath
+  };
+}
+
+export async function discardStagedSourceRecord(staged) {
+  await rm(staged.temporaryPath, { force: true });
+}
+
+export async function publishStagedSourceRecord(staged) {
+  await replaceRecord(staged.temporaryPath, staged.targetPath);
+}
+
+async function replaceRecord(temporaryPath, targetPath) {
+  await rename(temporaryPath, targetPath);
+}
+
+async function createRecord(temporaryPath, targetPath) {
+  await link(temporaryPath, targetPath);
+}
+
+async function assertExistingPathInsideRoot(rootDir, targetPath, errorMessage) {
+  const resolvedRoot = await realpath(path.resolve(rootDir));
+  let existingAncestor = targetPath;
+
+  while (true) {
+    try {
+      await lstat(existingAncestor);
+      break;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      const parent = path.dirname(existingAncestor);
+      if (parent === existingAncestor) throw error;
+      existingAncestor = parent;
+    }
+  }
+
+  const resolvedAncestor = await realpath(existingAncestor);
+  if (!isPathInsideOrEqual(resolvedRoot, resolvedAncestor)) {
+    throw new Error(errorMessage);
+  }
+}
+
+async function readRecord(filePath) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch (error) {
+    if (error instanceof SyntaxError) throw new Error(`Invalid source record JSON: ${filePath}`);
+    throw error;
+  }
+}
+
+async function findJsonFiles(directory) {
+  let entries;
+  try {
+    entries = await readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  }
+
+  const files = [];
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    const entryPath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await findJsonFiles(entryPath));
+    } else if (entry.isFile() && entry.name.endsWith('.json')) {
+      files.push(entryPath);
+    }
+  }
+  return files;
+}

package/lib/sourceRemoteArchiveAcquisitionAdapter.js

@@ -0,0 +1,147 @@
+import { getDomain } from 'tldts';
+import {
+  defineSourceAcquisitionAdapter
+} from './sourceAcquisitionAdapter.js';
+import { SourceAcquisitionError, sourceCollisionError } from './sourceAcquisitionError.js';
+import {
+  assertDirectorySourceMatchesRecord,
+  sameJson
+} from './sourceAcquisitionPolicy.js';
+import {
+  inspectRemoteArchive,
+  stageRemoteArchive
+} from './sourceArchiveWorkspace.js';
+import { parseRemoteArchiveRequest } from './sourceHttp.js';
+import { validateSourceId } from './sourceRegistry.js';
+import { sourceInstallPathAvailable } from './sourceTree.js';
+
+export function createRemoteArchiveAcquisitionAdapter(context, request) {
+  const parsed = parseRemoteArchiveRequest(request);
+
+  return defineSourceAcquisitionAdapter({
+    stalePlanMessage: 'Remote Archive changed since the add plan',
+    inspect: async () => buildRemoteArchiveCandidate(
+      parsed,
+      await inspectRemoteArchive(
+        context,
+        parsed,
+        'skillcaddy-archive-plan-'
+      )
+    ),
+    prepare: async (workspaceRoot) => buildRemoteArchiveCandidate(
+      parsed,
+      await stageRemoteArchive(context, parsed, workspaceRoot)
+    ),
+    resolveIdentity: (_candidate, records) =>
+      resolveArchiveIdentity(context.rootDir, records, parsed),
+    buildRecord(plan) {
+      return {
+        schemaVersion: 1,
+        sourceId: plan.sourceId,
+        bucket: 'official',
+        type: 'archive',
+        installPath: plan.installPath,
+        origin: plan.origin,
+        integrity: plan.integrity,
+        skills: plan.skills
+      };
+    },
+    matchesIdentity(record, plan) {
+      return record.type === 'archive' &&
+        record.installPath === plan.installPath;
+    },
+    matchesContent(record, plan) {
+      return record.integrity?.value === plan.integrity.value &&
+        sameJson(record.skills, plan.skills);
+    },
+    assertInstalled: assertDirectorySourceMatchesRecord
+  });
+}
+
+async function resolveArchiveIdentity(rootDir, records, parsed) {
+  if (parsed.namespace) {
+    return existingOrAvailableIdentity(
+      rootDir,
+      records,
+      archiveIdentity(parsed.namespace, parsed.name)
+    );
+  }
+
+  const defaultIdentity = archiveIdentity(null, parsed.name);
+  const sameDefault = records.find(
+    (record) => record.sourceId === defaultIdentity.sourceId
+  );
+  if (
+    sameDefault?.type === 'archive' &&
+    archiveDomain(sameDefault.origin.display) === parsed.registrableDomain
+  ) {
+    return {
+      sourceId: sameDefault.sourceId,
+      installPath: sameDefault.installPath
+    };
+  }
+  if (
+    !sameDefault &&
+    await sourceInstallPathAvailable(rootDir, records, defaultIdentity.installPath)
+  ) {
+    return defaultIdentity;
+  }
+  return existingOrAvailableIdentity(
+    rootDir,
+    records,
+    archiveIdentity(parsed.registrableDomain, parsed.name)
+  );
+}
+
+async function existingOrAvailableIdentity(rootDir, records, identity) {
+  const existing = records.find((record) => record.sourceId === identity.sourceId);
+  if (existing) {
+    return { sourceId: existing.sourceId, installPath: existing.installPath };
+  }
+  if (await sourceInstallPathAvailable(rootDir, records, identity.installPath)) {
+    return identity;
+  }
+  throw sourceCollisionError(`Source destination collision: ${identity.installPath}`);
+}
+
+function archiveIdentity(namespace, name) {
+  const sourceId = namespace
+    ? `official/${namespace}/${name}`
+    : `official/${name}`;
+  try {
+    validateSourceId(sourceId);
+  } catch {
+    throw new SourceAcquisitionError(
+      'unresolved-identity',
+      'Remote Archive name and namespace must form a safe source identity',
+      3
+    );
+  }
+  return {
+    sourceId,
+    installPath: `official/${namespace ? `${namespace}--` : ''}${name}`
+  };
+}
+
+function buildRemoteArchiveCandidate(parsed, candidate) {
+  return {
+    input: {
+      type: 'remote-zip',
+      display: parsed.display
+    },
+    origin: {
+      kind: parsed.protocol,
+      display: parsed.display
+    },
+    integrity: candidate.integrity,
+    skills: candidate.skills,
+    warnings: candidate.warnings,
+    ...(candidate.contentRoot ? { contentRoot: candidate.contentRoot } : {})
+  };
+}
+
+function archiveDomain(display) {
+  const hostname = new URL(display).hostname;
+  return getDomain(hostname, { allowPrivateDomains: true }) ||
+    hostname.toLowerCase();
+}

package/lib/sourceRemoteFileAcquisitionAdapter.js

@@ -0,0 +1,95 @@
+import {
+  defineSourceAcquisitionAdapter
+} from './sourceAcquisitionAdapter.js';
+import { SourceAcquisitionError } from './sourceAcquisitionError.js';
+import {
+  assertDirectorySourceMatchesRecord,
+  sameJson
+} from './sourceAcquisitionPolicy.js';
+import { parseRemoteSkillFileRequest } from './sourceHttp.js';
+import {
+  inspectRemoteSkillFile,
+  stageRemoteSkillFile
+} from './sourceRemoteFileWorkspace.js';
+import { validateSourceId } from './sourceRegistry.js';
+
+export function createRemoteFileAcquisitionAdapter(context, request) {
+  const parsed = parseRemoteSkillFileRequest(request);
+
+  return defineSourceAcquisitionAdapter({
+    stalePlanMessage: 'Remote SKILL.md changed since the add plan',
+    inspect: async () => buildRemoteFileCandidate(
+      parsed,
+      await inspectRemoteSkillFile(
+        context,
+        parsed,
+        'skillcaddy-remote-file-plan-'
+      )
+    ),
+    prepare: async (workspaceRoot) => buildRemoteFileCandidate(
+      parsed,
+      await stageRemoteSkillFile(context, parsed, workspaceRoot)
+    ),
+    resolveIdentity() {
+      return remoteFileIdentity(parsed.name);
+    },
+    buildRecord(plan) {
+      return {
+        schemaVersion: 1,
+        sourceId: plan.sourceId,
+        bucket: 'official',
+        type: 'remote-file',
+        installPath: plan.installPath,
+        origin: plan.origin,
+        integrity: plan.integrity,
+        skills: plan.skills
+      };
+    },
+    matchesIdentity(record, plan) {
+      return record.type === 'remote-file' &&
+        record.installPath === plan.installPath &&
+        record.origin.display === plan.origin.display;
+    },
+    matchesContent(record, plan) {
+      return record.integrity?.value === plan.integrity.value &&
+        sameJson(record.skills, plan.skills);
+    },
+    assertInstalled: assertDirectorySourceMatchesRecord
+  });
+}
+
+function remoteFileIdentity(name) {
+  if (name.includes('/')) throw remoteFileIdentityError();
+  const sourceId = `official/${name}`;
+  try {
+    validateSourceId(sourceId);
+  } catch {
+    throw remoteFileIdentityError();
+  }
+  return { sourceId, installPath: sourceId };
+}
+
+function remoteFileIdentityError() {
+  return new SourceAcquisitionError(
+    'unresolved-identity',
+    'Remote file name must be a single safe identity segment',
+    3
+  );
+}
+
+function buildRemoteFileCandidate(parsed, candidate) {
+  return {
+    input: {
+      type: 'remote-file',
+      display: parsed.display
+    },
+    origin: {
+      kind: parsed.protocol,
+      display: parsed.display
+    },
+    integrity: candidate.integrity,
+    skills: candidate.skills,
+    warnings: candidate.warnings,
+    ...(candidate.contentRoot ? { contentRoot: candidate.contentRoot } : {})
+  };
+}