@danieljvdm/dev-kit 0.4.0 → 0.5.0

package/src/sync.ts

@@ -3,7 +3,12 @@ import { Cause, Effect, FileSystem, Path, Schema, Stream } from "effect";
 import { ChildProcess } from "effect/unstable/process";
 
 import { DevKitManifestSchema, normalizeManifest } from "./manifest.ts";
-import { loadSkillCatalog, resolveSkillSources, type ResolvedSkillSource } from "./catalog.ts";
+import {
+  loadSkillCatalog,
+  resolveSkillSources,
+  type CatalogSkill,
+  type ResolvedSkillSource,
+} from "./catalog.ts";
 import { printDetail, printStatus, withSpinner } from "./cli-ui.ts";
 import {
   applyEffectSourcePlan,
@@ -21,11 +26,15 @@ import {
   observePath,
   type ObservedPath,
 } from "./path-digest.ts";
+import { resolvePackageSkillSelector } from "./package-skill-source.ts";
+import { parseSkillSelector } from "./skill-selector.ts";
 import {
   AppliedStateSchema,
   DevKitLockSchema,
   type AppliedState,
   type DevKitLock,
+  type ManagedInstructionOutput,
+  type ManagedOutput,
   type ManagedSkillOutput,
   type OwnershipReceipt,
 } from "./project-state.ts";
@@ -67,10 +76,17 @@ type DesiredSkillOutput =
       readonly linkTarget: string;
     });
 
+type DesiredInstructionOutput = ManagedInstructionOutput & {
+  readonly destination: string;
+  readonly linkTarget: string;
+};
+
+type DesiredOutput = DesiredSkillOutput | DesiredInstructionOutput;
+
 type SkillPlanAction =
   | {
       readonly action: "create" | "update";
-      readonly desired: DesiredSkillOutput;
+      readonly desired: DesiredOutput;
       readonly observed: ObservedPath;
     }
   | {
@@ -81,7 +97,7 @@ type SkillPlanAction =
     }
   | {
       readonly action: "unchanged";
-      readonly desired: DesiredSkillOutput;
+      readonly desired: DesiredOutput;
       readonly observed: ObservedPath;
       readonly adopted: boolean;
     }
@@ -263,7 +279,7 @@ const expandSelection = (
   for (const name of include) {
     if (skillFamilies[name]) {
       for (const skill of skillFamilies[name]) selected.add(skill);
-    } else if (availableSkills.includes(name)) {
+    } else if (availableSkills.includes(name) || parseSkillSelector(name)?.type === "package") {
       selected.add(name);
     } else {
       return Effect.fail(new UnknownSkillOrFamilyError({ name, known }));
@@ -315,7 +331,7 @@ const pathsOverlap = (left: string, right: string): boolean =>
 const validateReservedPaths = Effect.fn("validateReservedPaths")(function* (
   projectDir: string,
   reserved: ReadonlyArray<{ readonly label: string; readonly path: string }>,
-  outputs: ReadonlyArray<Pick<ManagedSkillOutput | OwnershipReceipt, "path">>,
+  outputs: ReadonlyArray<Pick<ManagedOutput | OwnershipReceipt, "path">>,
 ) {
   const outputPaths = new Set<string>();
   for (const output of outputs) {
@@ -342,19 +358,21 @@ const validateReservedPaths = Effect.fn("validateReservedPaths")(function* (
   }
 });
 
-const outputIdentity = (output: Pick<ManagedSkillOutput, "resourceId" | "path" | "mode" | "kind" | "digest" | "catalog">) =>
+const outputIdentity = (output: ManagedOutput) =>
   JSON.stringify({
     resourceId: output.resourceId,
     path: output.path,
     mode: output.mode,
     kind: output.kind,
     digest: output.digest,
-    catalog: output.catalog,
+    ...("skill" in output
+      ? { skill: output.skill, target: output.target, catalog: output.catalog }
+      : { sourcePath: output.sourcePath }),
   });
 
 const validateInventory = Effect.fn("validateManagedInventory")(function* (
   projectDir: string,
-  outputs: ReadonlyArray<ManagedSkillOutput | OwnershipReceipt>,
+  outputs: ReadonlyArray<ManagedOutput | OwnershipReceipt>,
   label: string,
 ) {
   const ids = new Set<string>();
@@ -384,7 +402,7 @@ const validateInventory = Effect.fn("validateManagedInventory")(function* (
 
 const validateCrossInventoryPaths = Effect.fn("validateCrossInventoryPaths")(function* (
   projectDir: string,
-  outputs: ReadonlyArray<Pick<ManagedSkillOutput | OwnershipReceipt, "path">>,
+  outputs: ReadonlyArray<Pick<ManagedOutput | OwnershipReceipt, "path">>,
 ) {
   const uniquePaths = new Set<string>();
   for (const output of outputs) {
@@ -406,16 +424,49 @@ const validateCrossInventoryPaths = Effect.fn("validateCrossInventoryPaths")(fun
 const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
   projectDir: string,
   sourceBySkill: ReadonlyMap<string, ResolvedSkillSource>,
-  skills: ReadonlyArray<string>,
+  skills: ReadonlyArray<CatalogSkill>,
+  setup: ReturnType<typeof normalizeManifest>["setup"],
   targets: ReturnType<typeof normalizeManifest>["targets"],
 ) {
   const path = yield* Path.Path;
-  const outputs: Array<DesiredSkillOutput> = [];
+  const outputs: Array<DesiredOutput> = [];
+  if (setup.claudeInstructions.enabled) {
+    const source = yield* resolveManagedPath(projectDir, "AGENTS.md");
+    const sourceObservation = yield* observePath(source.absolute);
+    if (sourceObservation.kind !== "file") {
+      return yield* new InvalidProjectStateError({
+        message: "Claude instructions source is not a regular file: AGENTS.md",
+      });
+    }
+    const managed = yield* resolveManagedPath(projectDir, "CLAUDE.md");
+    const linkTarget = path.relative(path.dirname(managed.absolute), source.absolute);
+    outputs.push({
+      resourceId: "setup:claude-instructions",
+      path: managed.relative,
+      sourcePath: source.relative,
+      mode: "symlink",
+      kind: "symlink",
+      digest: yield* digestSymlinkTarget(linkTarget),
+      destination: managed.absolute,
+      linkTarget,
+    });
+  }
   const agentsTarget = targets.agents;
+  const duplicateOutput = skills.find((skill, index) =>
+    skills.findIndex((candidate) => candidate.name === skill.name) !== index
+  );
+  if (duplicateOutput !== undefined) {
+    const selectors = skills
+      .filter((skill) => skill.name === duplicateOutput.name)
+      .map((skill) => skill.selector);
+    return yield* new InvalidProjectStateError({
+      message: `selected skills would both install as ${duplicateOutput.name}: ${selectors.join(", ")}`,
+    });
+  }
   for (const skill of skills) {
-    const resolvedSource = sourceBySkill.get(skill);
+    const resolvedSource = sourceBySkill.get(skill.selector);
     if (resolvedSource === undefined) {
-      return yield* new InvalidProjectStateError({ message: `skill source is unavailable: ${skill}` });
+      return yield* new InvalidProjectStateError({ message: `skill source is unavailable: ${skill.selector}` });
     }
     const source = resolvedSource.path;
     const sourceObservation = yield* observePath(source);
@@ -425,12 +476,12 @@ const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
     for (const targetName of ["agents", "claude", "opencode"] as const) {
       const target = targets[targetName];
       if (!target.enabled) continue;
-      const managed = yield* resolveManagedPath(projectDir, path.join(target.path, skill));
+      const managed = yield* resolveManagedPath(projectDir, path.join(target.path, skill.name));
       if (target.mode === "copy") {
         outputs.push({
-          resourceId: `skill:${skill}@${targetName}`,
+          resourceId: `skill:${skill.selector}@${targetName}`,
           path: managed.relative,
-          skill,
+          skill: skill.name,
           target: targetName,
           mode: "copy",
           kind: "directory",
@@ -443,14 +494,14 @@ const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
       }
       const linkSource =
         targetName === "agents" || !agentsTarget.enabled
-          ? source
-          : (yield* resolveManagedPath(projectDir, path.join(agentsTarget.path, skill))).absolute;
+          ? resolvedSource.linkPath ?? source
+          : (yield* resolveManagedPath(projectDir, path.join(agentsTarget.path, skill.name))).absolute;
       const linkTarget = path.relative(path.dirname(managed.absolute), linkSource);
       const linkDigest = yield* digestSymlinkTarget(linkTarget);
       outputs.push({
-        resourceId: `skill:${skill}@${targetName}`,
+        resourceId: `skill:${skill.selector}@${targetName}`,
         path: managed.relative,
-        skill,
+        skill: skill.name,
         target: targetName,
         mode: "symlink",
         kind: "symlink",
@@ -471,7 +522,7 @@ const canonicalState = (state: AppliedState): string => `${JSON.stringify(state,
 
 const planDesiredOutputs = Effect.fn("planDesiredSkillOutputs")(function* (
   projectDir: string,
-  desired: ReadonlyArray<DesiredSkillOutput>,
+  desired: ReadonlyArray<DesiredOutput>,
   currentLock: DevKitLock | undefined,
   currentState: AppliedState | undefined,
   nextLock: DevKitLock,
@@ -587,8 +638,8 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
         typescriptPackage: manifest.setup.effectTsgo.typescriptPackage,
       })
     : undefined;
-  const catalog = yield* loadSkillCatalog(packageRoot);
-  const availableSkills = catalog.skills.map((skill) => skill.name);
+  const catalog = yield* loadSkillCatalog(packageRoot, projectDir);
+  const availableSkills = catalog.skills.map((skill) => skill.selector);
   const skillFamilies = { ...SKILL_FAMILIES, ...catalog.families };
   for (const [family, familySkills] of Object.entries(skillFamilies)) {
     if (availableSkills.includes(family)) {
@@ -599,12 +650,35 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
       return yield* new InvalidSkillCatalogError({ family, message: `family references missing skills: ${missing.join(", ")}` });
     }
   }
-  const selectedSkills = yield* expandSelection(manifest.include, manifest.exclude, availableSkills, skillFamilies);
+  const selectedSelectors = yield* expandSelection(manifest.include, manifest.exclude, availableSkills, skillFamilies);
+  const catalogBySelector = new Map(catalog.skills.map((skill) => [skill.selector, skill]));
   const sourceBySkill = yield* withSpinner(
-    "Fetching selected skills",
-    resolveSkillSources(packageRoot, projectDir, selectedSkills, options.dryRun !== true),
+    "Resolving selected skills",
+    resolveSkillSources(
+      packageRoot,
+      projectDir,
+      catalog,
+      selectedSelectors,
+      options.dryRun !== true,
+    ),
+  );
+  const selectedSkills: Array<CatalogSkill> = [];
+  for (const selector of selectedSelectors) {
+    const catalogSkill = catalogBySelector.get(selector);
+    if (catalogSkill === undefined) {
+      return yield* new InvalidProjectStateError({
+        message: `selected skill is unavailable: ${selector}`,
+      });
+    }
+    selectedSkills.push(catalogSkill);
+  }
+  const desired = yield* buildDesiredOutputs(
+    projectDir,
+    sourceBySkill,
+    selectedSkills,
+    manifest.setup,
+    manifest.targets,
   );
-  const desired = yield* buildDesiredOutputs(projectDir, sourceBySkill, selectedSkills, manifest.targets);
   const nextLock: DevKitLock = {
     version: 1,
     toolVersion: DEV_KIT_VERSION,
@@ -631,16 +705,27 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
             },
           }),
     },
-    outputs: desired.map(({ resourceId, path: outputPath, skill, target, mode, kind, digest, catalog }) => ({
-      resourceId,
-      path: outputPath,
-      skill,
-      target,
-      mode,
-      kind,
-      digest,
-      ...(catalog ? { catalog } : {}),
-    })),
+    outputs: desired.map((output): ManagedOutput =>
+      "skill" in output
+        ? {
+            resourceId: output.resourceId,
+            path: output.path,
+            skill: output.skill,
+            target: output.target,
+            mode: output.mode,
+            kind: output.kind,
+            digest: output.digest,
+            ...(output.catalog ? { catalog: output.catalog } : {}),
+          }
+        : {
+            resourceId: output.resourceId,
+            path: output.path,
+            sourcePath: output.sourcePath,
+            mode: output.mode,
+            kind: output.kind,
+            digest: output.digest,
+          },
+    ),
   };
   const reservedPaths = [
     { label: "manifest", path: manifestManaged.relative },
@@ -692,7 +777,10 @@ const formatAction = (action: SkillPlanAction): string => {
   const verb = action.desired.mode === "copy" ? "copy" : "link";
   const adoption = action.action === "unchanged" && action.adopted ? " (adopt)" : "";
   const marker = action.action === "create" ? "+" : action.action === "update" ? "~" : "=";
-  return `${marker} ${verb} ${action.desired.skill} → ${action.desired.path}${adoption}`;
+  const source = "skill" in action.desired
+    ? action.desired.skill
+    : action.desired.sourcePath;
+  return `${marker} ${verb} ${source} → ${action.desired.path}${adoption}`;
 };
 
 const operationalChangeCount = (plan: SkillPlan): number =>
@@ -734,6 +822,47 @@ const observationsEqual = (left: ObservedPath, right: ObservedPath): boolean =>
   left.kind === right.kind &&
   (left.kind === "missing" || (right.kind !== "missing" && left.digest === right.digest));
 
+const findNestedSymbolicLink = Effect.fn("findNestedSkillSymbolicLink")(function* (
+  root: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const pending = [root];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (current === undefined) continue;
+    if ((yield* observeSymbolicLink(current)).kind === "symlink") return current;
+    const info = yield* fs.stat(current);
+    if (info.type !== "Directory") continue;
+    for (const entry of yield* fs.readDirectory(current)) {
+      pending.push(path.join(current, entry));
+    }
+  }
+  return undefined;
+});
+
+const verifyPackageSkillSources = Effect.fn("verifyPackageSkillSources")(function* (
+  plan: SkillPlan,
+) {
+  const verified = new Set<string>();
+  for (const action of plan.actions) {
+    if (action.action === "remove" || action.action === "conflict") continue;
+    if (!("skill" in action.desired)) continue;
+    const catalog = action.desired.catalog;
+    if (catalog === undefined || !("package" in catalog)) continue;
+    const selector = `${catalog.package}#${catalog.skill}`;
+    const key = `${selector}\0${catalog.version}\0${catalog.digest}`;
+    if (verified.has(key)) continue;
+    const resolved = yield* resolvePackageSkillSelector(plan.projectDir, selector);
+    const observation = yield* observePath(resolved.path);
+    if (resolved.path !== action.desired.source || resolved.version !== catalog.version ||
+      observation.kind !== "directory" || observation.digest !== catalog.digest) {
+      return yield* new ApplyRaceError({ path: action.desired.source });
+    }
+    verified.add(key);
+  }
+});
+
 const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function* (plan: SkillPlan) {
   const conflicts = plan.actions.filter((action) => action.action === "conflict");
   if (conflicts.length > 0) {
@@ -770,6 +899,12 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
     yield* fs.makeDirectory(path.dirname(staged), { recursive: true });
     if (action.desired.mode === "copy") {
       yield* fs.copy(action.desired.source, staged, { overwrite: true });
+      const symbolicLink = yield* findNestedSymbolicLink(staged);
+      if (symbolicLink !== undefined) {
+        return yield* new InvalidProjectStateError({
+          message: `staged skill contains a symlink: ${action.desired.path}`,
+        });
+      }
     } else {
       yield* fs.symlink(action.desired.linkTarget, staged);
     }
@@ -780,6 +915,8 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
     stagedByResource.set(action.desired.resourceId, staged);
   }
 
+  yield* verifyPackageSkillSources(plan);
+
   const stagedLock = path.join(tempDir, "next-lock.json");
   const stagedState = path.join(tempDir, "next-state.json");
   yield* fs.writeFileString(stagedLock, canonicalLock(plan.nextLock));