skillcaddy 0.27.0

package/lib/sourceGitBatchUpdate.js

@@ -0,0 +1,168 @@
+import { readSourceRecords } from './sourceRegistry.js';
+import {
+  applySourceUpgrade,
+  planSourceUpgrade
+} from './sourceUpgrade.js';
+
+export async function updateRegisteredGitSources(
+  context,
+  { allowBreaking = false } = {}
+) {
+  const records = await readSourceRecords(context.rootDir);
+  const sources = [];
+  const networkFailureLimit = normalizeNetworkFailureLimit(
+    context.gitNetworkFailureLimit
+  );
+  let consecutiveNetworkFailures = 0;
+
+  for (const record of records.filter((candidate) => candidate.type === 'git')) {
+    if (consecutiveNetworkFailures >= networkFailureLimit) {
+      sources.push(batchResult(
+        record.sourceId,
+        'failed',
+        'git-network-circuit-open',
+        false,
+        undefined,
+        `Skipped after ${networkFailureLimit} consecutive Git network failures`
+      ));
+      continue;
+    }
+
+    try {
+      const plan = await planSourceUpgrade(context, {
+        request: { sourceId: record.sourceId },
+        authorization: {
+          kind: allowBreaking ? 'breaking' : 'ordinary'
+        }
+      });
+      const application = await applySourceUpgrade(context, plan);
+      if (plan.changes.removedOrRelocated.length > 0) {
+        sources.push(batchResult(
+          record.sourceId,
+          'breaking',
+          'breaking-replacement',
+          true,
+          plan.affectedProjectLinks,
+          undefined,
+          buildUpdateSummary(plan),
+          plan.affectedGlobalLinks,
+          plan.affectedHermesLinks
+        ));
+      } else {
+        sources.push(
+          application.result.status === 'dirty'
+            ? batchResult(
+                record.sourceId,
+                'dirty',
+                'dirty-worktree',
+                false,
+                undefined,
+                'Local Git changes found; update skipped'
+              )
+            : batchResult(
+                record.sourceId,
+                application.result.status,
+                undefined,
+                undefined,
+                undefined,
+                undefined,
+                application.result.status === 'updated'
+                  ? buildUpdateSummary(plan)
+                  : undefined
+              )
+        );
+      }
+      consecutiveNetworkFailures = 0;
+    } catch (error) {
+      consecutiveNetworkFailures = error.category === 'git-network'
+        ? consecutiveNetworkFailures + 1
+        : 0;
+      if (error.category === 'breaking-replacement') {
+        sources.push(batchResult(
+          record.sourceId,
+          'breaking',
+          'breaking-replacement',
+          false,
+          allowBreaking ? [] : error.affectedProjectLinks,
+          undefined,
+          undefined,
+          allowBreaking ? [] : error.affectedGlobalLinks,
+          allowBreaking ? [] : error.affectedHermesLinks
+        ));
+      } else {
+        sources.push(batchResult(
+          record.sourceId,
+          'failed',
+          error.category || 'failure',
+          false,
+          undefined,
+          error.message || 'Git source update failed'
+        ));
+      }
+    }
+  }
+
+  return { sources };
+}
+
+function normalizeNetworkFailureLimit(value) {
+  if (value === undefined) return 3;
+  if (!Number.isInteger(value) || value < 1) {
+    throw new TypeError('gitNetworkFailureLimit must be a positive integer');
+  }
+  return value;
+}
+
+function batchResult(
+  sourceId,
+  status,
+  category,
+  applied,
+  affected,
+  message,
+  updateSummary,
+  affectedGlobalLinks,
+  affectedHermesLinks
+) {
+  return {
+    sourceId,
+    status,
+    ...(category ? { category } : {}),
+    ...(applied === undefined ? {} : { applied }),
+    ...(message ? { message } : {}),
+    ...(updateSummary ? { updateSummary } : {}),
+    ...(Array.isArray(affected) && affected.length > 0
+      ? {
+          affected: affected.map((link) => ({
+            alias: link.alias,
+            skillPath: link.skillPath
+          }))
+        }
+      : {}),
+    ...(Array.isArray(affectedGlobalLinks) && affectedGlobalLinks.length > 0
+      ? {
+          affectedGlobalLinks: affectedGlobalLinks.map((link) => ({
+            alias: link.alias,
+            skillPath: link.skillPath
+          }))
+        }
+      : {}),
+    ...(Array.isArray(affectedHermesLinks) && affectedHermesLinks.length > 0
+      ? {
+          affectedHermesLinks: affectedHermesLinks.map((link) => ({
+            alias: link.alias,
+            skillPath: link.skillPath
+          }))
+        }
+      : {})
+  };
+}
+
+function buildUpdateSummary(plan) {
+  if (!plan.skillChanges) return undefined;
+  return {
+    fromCommit: plan.currentCommit,
+    toCommit: plan.incomingCommit,
+    skillChanges: plan.skillChanges
+  };
+}

package/lib/sourceGitRepair.js

@@ -0,0 +1,227 @@
+import path from 'node:path';
+import { SourceAcquisitionError } from './sourceAcquisitionError.js';
+import { canonicalJson } from './canonicalJson.js';
+import { inspectGitRegistryRepair } from './sourceGitUpgradeAdapter.js';
+import {
+  assertNoAffectedLinks,
+  classifySkillChanges,
+  findAffectedGlobalLinks,
+  findAffectedHermesLinks,
+  findAffectedProjectLinks
+} from './sourceUpgradePolicy.js';
+import { readSourceRecords, writeSourceRecord } from './sourceRegistry.js';
+import { validateSourceId } from './sourceRecord.js';
+
+const repairPlans = new WeakMap();
+
+export async function planGitSourceRepair(context, command) {
+  const authorization = requireAuthorization(command?.authorization);
+  const prepared = await buildRepairPlan(context, command?.request);
+  authorization.enforce(prepared.plan);
+  repairPlans.set(prepared.plan, {
+    authorization,
+    originalFingerprint: fingerprintRepairPlan(prepared.plan),
+    request: { sourceId: prepared.plan.sourceId }
+  });
+  return prepared.plan;
+}
+
+export async function applyGitSourceRepair(context, plan) {
+  const session = repairPlans.get(plan);
+  if (!session) {
+    assertRepairPlan(plan);
+    throw new Error(
+      'The Git registry repair plan must be applied by the process that created it'
+    );
+  }
+
+  assertSameRepairPlan(
+    session.originalFingerprint,
+    plan,
+    'Git source changed since the registry repair plan'
+  );
+  assertRepairPlan(plan);
+
+  const replanned = await buildRepairPlan(context, session.request);
+  session.authorization.enforce(replanned.plan);
+  assertSameRepairPlan(
+    session.originalFingerprint,
+    replanned.plan,
+    'Git source changed since the registry repair plan'
+  );
+
+  if (replanned.plan.status !== 'ready') {
+    return buildRepairResult(replanned.plan);
+  }
+
+  const rootDir = requireRootDir(context);
+  const record = replanned.record;
+  await writeSourceRecord(rootDir, {
+    ...record,
+    origin: {
+      ...record.origin,
+      commit: replanned.plan.currentCommit
+    },
+    skills: replanned.plan.skills
+  });
+  return buildRepairResult(replanned.plan, 'repaired');
+}
+
+async function buildRepairPlan(context, request) {
+  const rootDir = requireRootDir(context);
+  const projectPath = requireProjectPath(context);
+  const sourceId = requireSourceId(request);
+  const record = await findGitRecord(rootDir, sourceId);
+  const candidate = await inspectGitRegistryRepair(context, record);
+  const changes = classifySkillChanges(record.skills, candidate.skills);
+  const affectedProjectLinks = candidate.status === 'dirty'
+    ? []
+    : await findAffectedProjectLinks({
+        rootDir,
+        projectPath,
+        installPath: record.installPath,
+        removedSkillPaths: changes.removedOrRelocated
+      });
+  const affectedGlobalLinks = candidate.status === 'dirty'
+    ? []
+    : await findAffectedGlobalLinks({
+        rootDir,
+        globalDir: context.globalDir,
+        installPath: record.installPath,
+        removedSkillPaths: changes.removedOrRelocated
+      });
+  const affectedHermesLinks = candidate.status === 'dirty'
+    ? []
+    : await findAffectedHermesLinks({
+        rootDir,
+        hermesDir: context.hermesDir,
+        installPath: record.installPath,
+        removedSkillPaths: changes.removedOrRelocated
+      });
+
+  return {
+    record,
+    plan: {
+      operation: 'repair-source-registry',
+      status: candidate.status,
+      sourceId,
+      installPath: record.installPath,
+      input: {
+        type: 'git',
+        remote: record.origin.remote
+      },
+      registeredCommit: record.origin.commit,
+      currentCommit: candidate.currentCommit,
+      skills: candidate.skills,
+      warnings: candidate.warnings,
+      changes,
+      affectedProjectLinks,
+      ...(affectedGlobalLinks.length > 0 ? { affectedGlobalLinks } : {}),
+      ...(affectedHermesLinks.length > 0 ? { affectedHermesLinks } : {})
+    }
+  };
+}
+
+async function findGitRecord(rootDir, sourceId) {
+  const records = await readSourceRecords(rootDir);
+  const record = records.find((candidate) => candidate.sourceId === sourceId);
+  if (!record) {
+    throw new SourceAcquisitionError(
+      'unresolved-identity',
+      `Source is not registered: ${sourceId}`,
+      3
+    );
+  }
+  if (record.type !== 'git') {
+    throw new SourceAcquisitionError(
+      'unsupported-source',
+      `Git registry repair requires a Git source: ${sourceId}`
+    );
+  }
+  return record;
+}
+
+function buildRepairResult(plan, status = plan.status) {
+  return {
+    status: status === 'ready' ? 'repaired' : status,
+    sourceId: plan.sourceId,
+    installPath: plan.installPath,
+    commit: plan.currentCommit,
+    skills: plan.skills,
+    warnings: plan.warnings,
+    changes: plan.changes
+  };
+}
+
+function requireAuthorization(authorization) {
+  if (authorization?.kind === 'breaking') return { enforce() {} };
+  if (authorization?.kind === 'ordinary') {
+      return {
+        enforce: (plan) => assertNoAffectedLinks(
+          plan.affectedProjectLinks,
+          plan.affectedGlobalLinks,
+          plan.affectedHermesLinks
+        )
+      };
+  }
+  throw new Error('Git registry repair requires an authorization policy');
+}
+
+function requireRootDir(context) {
+  if (!context || typeof context.rootDir !== 'string' || !context.rootDir.trim()) {
+    throw new Error('Source management requires context.rootDir');
+  }
+  return path.resolve(context.rootDir);
+}
+
+function requireProjectPath(context) {
+  if (!context || typeof context.projectPath !== 'string' || !context.projectPath.trim()) {
+    throw new Error('Git registry repair requires context.projectPath');
+  }
+  return path.resolve(context.projectPath);
+}
+
+function requireSourceId(request) {
+  if (!request || typeof request.sourceId !== 'string' || !request.sourceId.trim()) {
+    throw new Error('Git registry repair requires request.sourceId');
+  }
+  if (request.input !== undefined) {
+    throw new Error('Git registry repair does not accept replacement input');
+  }
+  validateSourceId(request.sourceId);
+  return request.sourceId;
+}
+
+function assertRepairPlan(plan) {
+  if (
+    !plan ||
+    plan.operation !== 'repair-source-registry' ||
+    !['ready', 'current', 'dirty'].includes(plan.status)
+  ) {
+    throw new Error('A valid Git registry repair plan is required');
+  }
+}
+
+function fingerprintRepairPlan(plan) {
+  return canonicalJson({
+    operation: plan.operation,
+    status: plan.status,
+    sourceId: plan.sourceId,
+    installPath: plan.installPath,
+    input: plan.input,
+    registeredCommit: plan.registeredCommit,
+    currentCommit: plan.currentCommit,
+    skills: plan.skills,
+    warnings: plan.warnings,
+    changes: plan.changes,
+    affectedProjectLinks: plan.affectedProjectLinks,
+    affectedGlobalLinks: plan.affectedGlobalLinks,
+    affectedHermesLinks: plan.affectedHermesLinks
+  });
+}
+
+function assertSameRepairPlan(originalFingerprint, plan, message) {
+  if (originalFingerprint !== fingerprintRepairPlan(plan)) {
+    throw new SourceAcquisitionError('stale-plan', message);
+  }
+}

package/lib/sourceGitStaging.js

@@ -0,0 +1,139 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { SourceAcquisitionError } from './sourceAcquisitionError.js';
+import { SOURCE_INSTALLING_MARKER } from './sourcePolicy.js';
+import { sourcePathExists, validateSourceTree } from './sourceTree.js';
+import { validateStagedSource } from './sourceValidation.js';
+
+const execFile = promisify(execFileCallback);
+
+export async function cloneAndInspectGitSource(stagingRoot, parsed) {
+  const contentRoot = path.join(stagingRoot, 'repository');
+  const cloneArguments = ['clone', '--', parsed.cloneRemote, contentRoot];
+
+  try {
+    await execFile('git', cloneArguments);
+  } catch (error) {
+    throw gitError(`Could not clone Git source: ${safeGitError(error)}`);
+  }
+
+  try {
+    const focus = parsed.treeSegments
+      ? await checkoutGitHubTreeRef(contentRoot, parsed.treeSegments)
+      : undefined;
+    if (await sourcePathExists(path.join(contentRoot, SOURCE_INSTALLING_MARKER))) {
+      throw new SourceAcquisitionError(
+        'source-validation',
+        `Git source contains reserved publication marker: ${SOURCE_INSTALLING_MARKER}`
+      );
+    }
+    await validateSourceTree(stagingRoot, contentRoot);
+    const validated = await validateStagedSource(contentRoot);
+    assertFocusContainsSkill(validated.skills, focus);
+    const [{ stdout: commitOutput }, ref] = await Promise.all([
+      execFile('git', ['-C', contentRoot, 'rev-parse', 'HEAD']),
+      readCheckedOutRef(contentRoot)
+    ]);
+    return {
+      contentRoot,
+      commit: commitOutput.trim(),
+      ref,
+      ...(focus ? { focus } : {}),
+      skills: validated.skills,
+      warnings: validated.warnings
+    };
+  } catch (error) {
+    if (error instanceof SourceAcquisitionError) throw error;
+    throw gitError(error.message);
+  }
+}
+
+async function checkoutGitHubTreeRef(sourcePath, treeSegments) {
+  const { stdout } = await execFile('git', [
+    '-C',
+    sourcePath,
+    'for-each-ref',
+    '--format=%(refname:strip=3)',
+    'refs/remotes/origin'
+  ]);
+  const branches = stdout
+    .split('\n')
+    .map((branch) => branch.trim())
+    .filter((branch) => branch && branch !== 'HEAD')
+    .filter((branch) => {
+      const branchSegments = branch.split('/');
+      return branchSegments.every((segment, index) => treeSegments[index] === segment);
+    })
+    .sort((left, right) => right.split('/').length - left.split('/').length);
+  const ref = branches[0];
+  if (!ref) {
+    throw gitError('GitHub tree URL does not match a repository branch');
+  }
+
+  await execFile('git', [
+    '-C',
+    sourcePath,
+    'checkout',
+    '--quiet',
+    '-B',
+    ref,
+    `origin/${ref}`
+  ]);
+  const focusSegments = treeSegments.slice(ref.split('/').length);
+  return {
+    ref,
+    ...(focusSegments.length > 0 ? { path: focusSegments.join('/') } : {})
+  };
+}
+
+export function prioritizeFocusedSkills(skills, focus) {
+  if (!focus?.path) return skills;
+  return [...skills].sort((left, right) => {
+    const leftFocused = left === focus.path || left.startsWith(`${focus.path}/`);
+    const rightFocused = right === focus.path || right.startsWith(`${focus.path}/`);
+    return Number(rightFocused) - Number(leftFocused) || left.localeCompare(right);
+  });
+}
+
+async function readCheckedOutRef(sourcePath) {
+  try {
+    const { stdout } = await execFile('git', [
+      '-C',
+      sourcePath,
+      'symbolic-ref',
+      '--quiet',
+      '--short',
+      'HEAD'
+    ]);
+    return stdout.trim();
+  } catch {
+    throw gitError('Git source must check out a branch');
+  }
+}
+
+function assertFocusContainsSkill(skills, focus) {
+  if (!focus?.path) return;
+  const containsSkill = skills.some(
+    (skillPath) => skillPath === focus.path || skillPath.startsWith(`${focus.path}/`)
+  );
+  if (!containsSkill) {
+    throw new SourceAcquisitionError(
+      'source-validation',
+      `GitHub source focus contains no scanner-visible skill: ${focus.path}`
+    );
+  }
+}
+
+function safeGitError(error) {
+  const message = typeof error?.stderr === 'string' && error.stderr.trim()
+    ? error.stderr.trim()
+    : error.message;
+  return String(message)
+    .replace(/(?:https|ssh):\/\/[^\s'"]+/gi, '[sanitized Git URL]')
+    .replace(/(?:[^\s@'"]+@)?[^\s:/'"]+:[^\s'"]+/g, '[sanitized Git URL]');
+}
+
+function gitError(message) {
+  return new SourceAcquisitionError('git-acquisition', message);
+}