skillcaddy 0.27.0

package/lib/sourceUpgradePolicy.js

@@ -0,0 +1,170 @@
+import path from 'node:path';
+import { canonicalJson } from './canonicalJson.js';
+import { SourceAcquisitionError } from './sourceAcquisitionError.js';
+import {
+  checksumDirectory,
+  sourcePathExists
+} from './sourceTree.js';
+import { scanEnabledSkills, scanGlobalSkills } from './skillStore.js';
+import { scanHermesSkills } from './hermesStore.js';
+
+export function fingerprintSourceUpgradePlan(plan) {
+  return canonicalJson({
+    operation: plan.operation,
+    status: plan.status,
+    sourceId: plan.sourceId,
+    installPath: plan.installPath,
+    input: plan.input,
+    origin: plan.origin,
+    integrity: plan.integrity,
+    currentCommit: plan.currentCommit,
+    incomingCommit: plan.incomingCommit,
+    skills: plan.skills,
+    warnings: plan.warnings,
+    skillChanges: plan.skillChanges,
+    changes: plan.changes,
+    affectedProjectLinks: plan.affectedProjectLinks,
+    affectedGlobalLinks: plan.affectedGlobalLinks,
+    affectedHermesLinks: plan.affectedHermesLinks
+  });
+}
+
+export function assertSameSourceUpgradePlan(
+  originalFingerprint,
+  plan,
+  message
+) {
+  if (originalFingerprint !== fingerprintSourceUpgradePlan(plan)) {
+    throw new SourceAcquisitionError('stale-plan', message);
+  }
+}
+
+export function assertNoAffectedProjectLinks(affectedProjectLinks) {
+  return assertNoAffectedLinks(affectedProjectLinks, []);
+}
+
+export function assertNoAffectedLinks(
+  affectedProjectLinks,
+  affectedGlobalLinks = [],
+  affectedHermesLinks = []
+) {
+  if (
+    affectedProjectLinks.length === 0 &&
+    affectedGlobalLinks.length === 0 &&
+    affectedHermesLinks.length === 0
+  ) return;
+  const projectAliases = affectedProjectLinks.map((link) => link.alias).join(', ');
+  const globalAliases = affectedGlobalLinks.map((link) => link.alias).join(', ');
+  const hermesAliases = affectedHermesLinks.map((link) => link.alias).join(', ');
+  const details = [];
+  if (affectedProjectLinks.length > 0) details.push(`current-project links: ${projectAliases}`);
+  if (affectedGlobalLinks.length > 0) details.push(`global links: ${globalAliases}`);
+  if (affectedHermesLinks.length > 0) details.push(`Hermes links: ${hermesAliases}`);
+  const error = new SourceAcquisitionError(
+    'breaking-replacement',
+    `Source replacement would break ${details.join('; ')}. Re-run with --allow-breaking to authorize it.`,
+    4
+  );
+  error.affectedProjectLinks = affectedProjectLinks.map((link) => ({
+    alias: link.alias,
+    skillPath: link.skillPath
+  }));
+  error.affectedGlobalLinks = affectedGlobalLinks.map((link) => ({
+    alias: link.alias,
+    skillPath: link.skillPath
+  }));
+  error.affectedHermesLinks = affectedHermesLinks.map((link) => ({
+    alias: link.alias,
+    skillPath: link.skillPath
+  }));
+  throw error;
+}
+
+export async function findAffectedProjectLinks({
+  rootDir,
+  projectPath,
+  installPath,
+  removedSkillPaths
+}) {
+  if (!projectPath || removedSkillPaths.length === 0) return [];
+  const removedByTarget = new Map(removedSkillPaths.map((skillPath) => [
+    path.resolve(rootDir, installPath, skillPath),
+    skillPath
+  ]));
+  const links = await scanEnabledSkills(projectPath);
+  return links
+    .filter((link) => link.isSymlink && removedByTarget.has(link.targetPath))
+    .map((link) => ({
+      alias: link.alias,
+      skillPath: removedByTarget.get(link.targetPath)
+    }));
+}
+
+export async function findAffectedGlobalLinks({
+  rootDir,
+  globalDir,
+  installPath,
+  removedSkillPaths
+}) {
+  if (removedSkillPaths.length === 0) return [];
+  const removedByTarget = new Map(removedSkillPaths.map((skillPath) => [
+    path.resolve(rootDir, installPath, skillPath),
+    skillPath
+  ]));
+  const links = await scanGlobalSkills({ globalDir });
+  return links
+    .filter((link) => link.isSymlink && removedByTarget.has(link.targetPath))
+    .map((link) => ({
+      alias: link.alias,
+      skillPath: removedByTarget.get(link.targetPath)
+    }));
+}
+
+export async function findAffectedHermesLinks({
+  rootDir,
+  hermesDir,
+  installPath,
+  removedSkillPaths
+}) {
+  if (removedSkillPaths.length === 0) return [];
+  const removedByTarget = new Map(removedSkillPaths.map((skillPath) => [
+    path.resolve(rootDir, installPath, skillPath),
+    skillPath
+  ]));
+  const links = await scanHermesSkills({ hermesDir });
+  return links
+    .filter((link) => link.isSymlink && removedByTarget.has(link.targetPath))
+    .map((link) => ({
+      alias: link.alias,
+      skillPath: removedByTarget.get(link.targetPath)
+    }));
+}
+
+export async function assertActiveSourceMatchesRecord(destination, record) {
+  if (!(await sourcePathExists(destination))) {
+    throw new SourceAcquisitionError(
+      'source-collision',
+      `Registered source content is missing: ${record.sourceId}`,
+      3
+    );
+  }
+  if (await checksumDirectory(destination) !== record.integrity?.value) {
+    throw new SourceAcquisitionError(
+      'source-collision',
+      `Registered source content no longer matches its integrity: ${record.sourceId}`,
+      3
+    );
+  }
+}
+
+export function classifySkillChanges(previousSkills, nextSkills) {
+  const previous = new Set(previousSkills);
+  const next = new Set(nextSkills);
+  return {
+    unchanged: previousSkills.filter((skillPath) => next.has(skillPath)),
+    added: nextSkills.filter((skillPath) => !previous.has(skillPath)),
+    removedOrRelocated: previousSkills.filter(
+      (skillPath) => !next.has(skillPath)
+    )
+  };
+}

package/lib/sourceUpgradeTransaction.js

@@ -0,0 +1,202 @@
+/**
+ * Source upgrade transactions
+ *
+ * Two strategies for atomic source updates:
+ * - DIRECTORY_REPLACEMENT: For local, archive, and remote-file sources
+ * - GIT_FAST_FORWARD: For Git sources
+ *
+ * Both follow the same phase structure:
+ * - PREPARE: Stage content and registry entries
+ * - COMMIT: Make changes active
+ * - CLEANUP: Remove temporary artifacts (directory only)
+ * - ROLLBACK: Undo on failure
+ * - DISCARD: Clean up staging state
+ *
+ * See sourceUpgrade.js for the lifecycle orchestration.
+ */
+import { execFile as execFileCallback } from 'node:child_process';
+import {
+  lstat,
+  rename,
+  rm
+} from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { SourceAcquisitionError } from './sourceAcquisitionError.js';
+import {
+  discardStagedSourceRecord,
+  publishStagedSourceRecord,
+  stageSourceRecord,
+  writeSourceRecord
+} from './sourceRegistry.js';
+
+const execFile = promisify(execFileCallback);
+
+// === Directory Replacement Strategy ===
+// For local, archive, and remote-file sources
+
+export const defaultSourceUpdateFileOperations = { rename, rm };
+
+export async function prepareDirectorySourceReplacement({
+  rootDir,
+  destination,
+  stagingRoot,
+  preparedContentRoot,
+  nextRecord,
+  fileOperations
+}) {
+  const previousSource = path.join(stagingRoot, 'previous-source');
+  const previousRecord = path.join(stagingRoot, 'previous-record.json');
+  const stagedRecord = await stageSourceRecord(rootDir, nextRecord);
+  return {
+    destination,
+    fileOperations,
+    preparedContentRoot,
+    previousRecord,
+    previousSource,
+    stagedRecord
+  };
+}
+
+export async function commitDirectorySourceReplacement(state) {
+  await state.fileOperations.rename(state.destination, state.previousSource);
+  await state.fileOperations.rename(
+    state.preparedContentRoot,
+    state.destination
+  );
+  await state.fileOperations.rename(
+    state.stagedRecord.targetPath,
+    state.previousRecord
+  );
+  await state.fileOperations.rename(
+    state.stagedRecord.temporaryPath,
+    state.stagedRecord.targetPath
+  );
+}
+
+export async function cleanupDirectorySourceReplacement(state) {
+  await state.fileOperations.rm(
+    state.previousSource,
+    { recursive: true, force: true }
+  );
+  await state.fileOperations.rm(state.previousRecord, { force: true });
+}
+
+export async function rollbackDirectorySourceReplacement(state) {
+  if (await pathExists(state.previousRecord)) {
+    await restorePublishedPath({
+      fileOperations: state.fileOperations,
+      backup: state.previousRecord,
+      target: state.stagedRecord.targetPath,
+      removeOptions: { force: true }
+    });
+  }
+  if (await pathExists(state.previousSource)) {
+    await restorePublishedPath({
+      fileOperations: state.fileOperations,
+      backup: state.previousSource,
+      target: state.destination,
+      removeOptions: { recursive: true, force: true }
+    });
+  }
+}
+
+export async function discardDirectorySourceReplacement(state) {
+  await discardStagedSourceRecord(state.stagedRecord);
+}
+
+// === Git Fast-Forward Strategy ===
+// For Git sources
+
+export async function prepareGitSourceFastForward({
+  rootDir,
+  record,
+  nextRecord,
+  incomingCommit,
+  publishRecord = publishStagedSourceRecord
+}) {
+  return {
+    destination: path.resolve(rootDir, record.installPath),
+    incomingCommit,
+    previousRecord: record,
+    publishRecord,
+    recordPublished: false,
+    rootDir,
+    sourceId: record.sourceId,
+    stagedRecord: await stageSourceRecord(rootDir, nextRecord)
+  };
+}
+
+export async function commitGitSourceFastForward(state) {
+  await state.publishRecord(state.stagedRecord);
+  state.recordPublished = true;
+  await execGit(state.destination, [
+    'merge',
+    '--ff-only',
+    '--no-edit',
+    state.incomingCommit
+  ], state.sourceId, 'Could not fast-forward Git source');
+  const installedCommit = await readGitOutput(
+    state.destination,
+    ['rev-parse', 'HEAD']
+  );
+  if (installedCommit !== state.incomingCommit) {
+    throw gitUpdateError(
+      'git-update',
+      `Git source did not advance to the planned commit: ${state.sourceId}`
+    );
+  }
+}
+
+export async function rollbackGitSourceFastForward(state) {
+  if (!state.recordPublished) return;
+  await writeSourceRecord(state.rootDir, state.previousRecord);
+}
+
+export async function discardGitSourceFastForward(state) {
+  await discardStagedSourceRecord(state.stagedRecord);
+}
+
+// === Private helpers ===
+
+async function pathExists(targetPath) {
+  try {
+    await lstat(targetPath);
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+async function restorePublishedPath({
+  fileOperations,
+  backup,
+  target,
+  removeOptions
+}) {
+  await fileOperations.rm(target, removeOptions);
+  await fileOperations.rename(backup, target);
+}
+
+async function readGitOutput(directory, args) {
+  const result = await execGit(
+    directory,
+    args,
+    'source',
+    'Could not inspect Git source'
+  );
+  return result.stdout.trim();
+}
+
+async function execGit(directory, args, sourceId, action) {
+  try {
+    return await execFile('git', ['-C', directory, ...args]);
+  } catch {
+    throw gitUpdateError('git-update', `${action}: ${sourceId}`);
+  }
+}
+
+function gitUpdateError(category, message, exitCode = 1) {
+  return new SourceAcquisitionError(category, message, exitCode);
+}

package/lib/sourceValidation.js

@@ -0,0 +1,120 @@
+import { constants } from 'node:fs';
+import { access, lstat, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { SourceAcquisitionError } from './sourceAcquisitionError.js';
+import { discoverSourceSkillDirectories } from './sourceSkillDiscovery.js';
+
+const KNOWN_FRONTMATTER_FIELDS = new Set([
+  'allowed-tools',
+  'compatibility',
+  'description',
+  'disable-model-invocation',
+  'license',
+  'metadata',
+  'name'
+]);
+
+export async function validateStagedSource(sourceRoot) {
+  const skillDirectories = await discoverSourceSkillDirectories(sourceRoot);
+  if (skillDirectories.length === 0) {
+    throw validationError('No scanner-visible SKILL.md was found');
+  }
+
+  const skills = [];
+  const warnings = [];
+  for (const skillDirectory of skillDirectories) {
+    const skillPath = path.join(skillDirectory, 'SKILL.md');
+    const relativeDirectory = toRelativeSkillPath(sourceRoot, skillDirectory);
+    const content = await readRegularSkillFile(skillPath, relativeDirectory);
+    skills.push(relativeDirectory);
+    warnings.push(...qualityWarnings(relativeDirectory, content));
+  }
+
+  return { skills: skills.sort(), warnings };
+}
+
+async function readRegularSkillFile(skillPath, relativeDirectory) {
+  const displayPath = relativeDirectory === '.' ? 'SKILL.md' : `${relativeDirectory}/SKILL.md`;
+  const stat = await lstat(skillPath);
+  if (!stat.isFile()) {
+    throw validationError(`${displayPath} must be a regular file`);
+  }
+
+  try {
+    await access(skillPath, constants.R_OK);
+    const content = await readFile(skillPath, 'utf8');
+    if (!content.trim()) throw validationError(`${displayPath} must not be empty`);
+    return content;
+  } catch (error) {
+    if (error instanceof SourceAcquisitionError) throw error;
+    throw validationError(`${displayPath} must be readable`);
+  }
+}
+
+function qualityWarnings(skillPath, content) {
+  const frontmatter = parseFrontmatter(content);
+  if (!frontmatter) {
+    return [
+      warning('missing-frontmatter', skillPath, 'SKILL.md has no YAML frontmatter'),
+      warning('missing-description', skillPath, 'SKILL.md frontmatter has no description')
+    ];
+  }
+  if (frontmatter.malformed) {
+    return [
+      warning('malformed-frontmatter', skillPath, 'SKILL.md frontmatter is not closed'),
+      warning('missing-description', skillPath, 'SKILL.md frontmatter has no description')
+    ];
+  }
+
+  const warnings = [];
+  if (!hasDescription(frontmatter.fields)) {
+    warnings.push(warning(
+      'missing-description',
+      skillPath,
+      'SKILL.md frontmatter has no description'
+    ));
+  }
+  for (const field of frontmatter.fields.keys()) {
+    if (!KNOWN_FRONTMATTER_FIELDS.has(field)) {
+      warnings.push(warning(
+        'unknown-frontmatter-field',
+        skillPath,
+        `SKILL.md frontmatter contains unknown field: ${field}`
+      ));
+    }
+  }
+  return warnings;
+}
+
+function parseFrontmatter(content) {
+  const lines = content.replace(/\r\n/g, '\n').split('\n');
+  if (lines[0] !== '---') return null;
+  const closingIndex = lines.indexOf('---', 1);
+  if (closingIndex < 0) return { malformed: true, fields: new Map() };
+
+  const fields = new Map();
+  for (const line of lines.slice(1, closingIndex)) {
+    const match = line.match(/^([A-Za-z0-9_-]+)\s*:(.*)$/);
+    if (match) fields.set(match[1], match[2].trim());
+  }
+  return { malformed: false, fields };
+}
+
+function hasDescription(fields) {
+  if (!fields.has('description')) return false;
+  const value = fields.get('description');
+  return Boolean(value && !['""', "''", 'null', '~'].includes(value));
+}
+
+function warning(category, skillPath, message) {
+  return { category, skillPath, message };
+}
+
+function validationError(message) {
+  return new SourceAcquisitionError('source-validation', message);
+}
+
+function toRelativeSkillPath(sourceRoot, skillDirectory) {
+  const relative = path.relative(sourceRoot, skillDirectory);
+  return relative ? relative.split(path.sep).join('/') : '.';
+}

package/lib/sourceWorkspace.js

@@ -0,0 +1,37 @@
+import {
+  mkdtemp,
+  rm,
+  rmdir
+} from 'node:fs/promises';
+import path from 'node:path';
+import { SourceAcquisitionError } from './sourceAcquisitionError.js';
+import { ensureSourceDirectory } from './sourceTree.js';
+
+export async function createManagedSourceWorkspace(rootDir, prefix) {
+  const parent = await requireSafeDirectory(
+    rootDir,
+    '.skillcaddy',
+    'staging'
+  );
+  return {
+    parent,
+    root: await mkdtemp(path.join(parent, prefix))
+  };
+}
+
+export async function removeManagedSourceWorkspace(workspace) {
+  await rm(workspace.root, { recursive: true, force: true });
+  try {
+    await rmdir(workspace.parent);
+  } catch (error) {
+    if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error;
+  }
+}
+
+async function requireSafeDirectory(rootDir, ...segments) {
+  try {
+    return await ensureSourceDirectory(rootDir, ...segments);
+  } catch (error) {
+    throw new SourceAcquisitionError('source-safety', error.message);
+  }
+}