@danieljvdm/dev-kit 0.4.0 → 0.6.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,
@@ -16,16 +21,23 @@ import {
   type EffectTsgoPatchPlan,
 } from "./effect-tsgo.ts";
 import {
+  digestFileContent,
   digestSymlinkTarget,
   digestText,
   observePath,
   type ObservedPath,
 } from "./path-digest.ts";
+import { resolvePackageSkillSelector } from "./package-skill-source.ts";
+import { readDirectDependencyNames } from "./project-package.ts";
+import { parseSkillSelector } from "./skill-selector.ts";
 import {
   AppliedStateSchema,
   DevKitLockSchema,
   type AppliedState,
   type DevKitLock,
+  type ManagedAgentInstructionsOutput,
+  type ManagedClaudeInstructionsOutput,
+  type ManagedOutput,
   type ManagedSkillOutput,
   type OwnershipReceipt,
 } from "./project-state.ts";
@@ -67,10 +79,25 @@ type DesiredSkillOutput =
       readonly linkTarget: string;
     });
 
+type DesiredAgentInstructionsOutput = ManagedAgentInstructionsOutput & {
+  readonly content: string;
+  readonly destination: string;
+};
+
+type DesiredClaudeInstructionsOutput = ManagedClaudeInstructionsOutput & {
+  readonly destination: string;
+  readonly linkTarget: string;
+};
+
+type DesiredOutput =
+  | DesiredSkillOutput
+  | DesiredAgentInstructionsOutput
+  | DesiredClaudeInstructionsOutput;
+
 type SkillPlanAction =
   | {
       readonly action: "create" | "update";
-      readonly desired: DesiredSkillOutput;
+      readonly desired: DesiredOutput;
       readonly observed: ObservedPath;
     }
   | {
@@ -81,7 +108,7 @@ type SkillPlanAction =
     }
   | {
       readonly action: "unchanged";
-      readonly desired: DesiredSkillOutput;
+      readonly desired: DesiredOutput;
       readonly observed: ObservedPath;
       readonly adopted: boolean;
     }
@@ -180,10 +207,14 @@ class ApplyRaceError extends Schema.TaggedErrorClass<ApplyRaceError>()("ApplyRac
   }
 }
 
-const SKILL_FAMILIES: SkillCatalog = { effect: ["effect-ts"] };
+const SKILL_FAMILIES: SkillCatalog = {
+  effect: ["effect-ts", "effect-atom-data-fetching"],
+};
 export const DEFAULT_MANIFEST = "dev-kit.jsonc";
 const DEFAULT_LOCKFILE = "dev-kit.lock.json";
 const DEFAULT_STATE = ".dev-kit/state.json";
+const AGENT_INSTRUCTIONS_TEMPLATE = "templates/AGENTS.md";
+const DEV_KIT_SKILL_PATH_PLACEHOLDER = "{{DEV_KIT_SKILL_PATH}}";
 
 const resolvePackageRoot = Effect.fn("resolvePackageRoot")(function* () {
   const path = yield* Path.Path;
@@ -263,7 +294,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 +346,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 +373,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 +417,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) {
@@ -403,19 +436,112 @@ const validateCrossInventoryPaths = Effect.fn("validateCrossInventoryPaths")(fun
   }
 });
 
+const renderAgentInstructions = Effect.fn("renderAgentInstructions")(function* (
+  packageRoot: string,
+  projectDir: string,
+  sourceBySkill: ReadonlyMap<string, ResolvedSkillSource>,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const templatePath = path.join(packageRoot, AGENT_INSTRUCTIONS_TEMPLATE);
+  if ((yield* observePath(templatePath)).kind !== "file") {
+    return yield* new InvalidProjectStateError({
+      message: `dev-kit agent instructions template is not a regular file: ${AGENT_INSTRUCTIONS_TEMPLATE}`,
+    });
+  }
+  const template = yield* fs.readFileString(templatePath);
+  if (!template.includes(DEV_KIT_SKILL_PATH_PLACEHOLDER)) {
+    return yield* new InvalidProjectStateError({
+      message: `dev-kit agent instructions template is missing ${DEV_KIT_SKILL_PATH_PLACEHOLDER}`,
+    });
+  }
+
+  const devKitSkill = sourceBySkill.get("dev-kit");
+  const devKitSkillPath = devKitSkill === undefined
+    ? "node_modules/@danieljvdm/dev-kit/skills/dev-kit/SKILL.md"
+    : portablePath(
+        path,
+        path.relative(
+          projectDir,
+          path.join(devKitSkill.linkPath ?? devKitSkill.path, "SKILL.md"),
+        ),
+      );
+  const sections = [template.replaceAll(DEV_KIT_SKILL_PATH_PLACEHOLDER, devKitSkillPath).trimEnd()];
+  if ((yield* readDirectDependencyNames(projectDir)).includes("vite-plus")) {
+    const vitePlusTemplate = path.join(projectDir, "node_modules", "vite-plus", "AGENTS.md");
+    if ((yield* observePath(vitePlusTemplate)).kind !== "file") {
+      return yield* new InvalidProjectStateError({
+        message: "Vite+ is a direct dependency but its agent instructions are not a regular file: node_modules/vite-plus/AGENTS.md",
+      });
+    }
+    sections.push((yield* fs.readFileString(vitePlusTemplate)).trim());
+  }
+  return `${sections.join("\n\n")}\n`;
+});
+
 const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
+  packageRoot: string,
   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.agentInstructions.enabled) {
+    const managed = yield* resolveManagedPath(projectDir, "AGENTS.md");
+    const content = yield* renderAgentInstructions(packageRoot, projectDir, sourceBySkill);
+    outputs.push({
+      resourceId: "setup:agent-instructions",
+      path: managed.relative,
+      sourcePath: AGENT_INSTRUCTIONS_TEMPLATE,
+      mode: "copy",
+      kind: "file",
+      digest: yield* digestFileContent(content),
+      destination: managed.absolute,
+      content,
+    });
+  }
+  if (setup.claudeInstructions.enabled) {
+    const source = yield* resolveManagedPath(projectDir, "AGENTS.md");
+    const sourceObservation = setup.agentInstructions.enabled
+      ? undefined
+      : yield* observePath(source.absolute);
+    if (!setup.agentInstructions.enabled && 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 +551,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 +569,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 +597,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 +713,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 +725,36 @@ 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(
+    packageRoot,
+    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 +781,38 @@ 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 => {
+      if ("skill" in output) {
+        return {
+          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 } : {}),
+        };
+      }
+      if (output.resourceId === "setup:agent-instructions") {
+        return {
+          resourceId: output.resourceId,
+          path: output.path,
+          sourcePath: output.sourcePath,
+          mode: output.mode,
+          kind: output.kind,
+          digest: output.digest,
+        };
+      }
+      return {
+        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 },
@@ -654,6 +826,17 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
   yield* validateReservedPaths(projectDir, reservedPaths, desired);
   const currentLock = yield* readOptionalStructuredFile(lockManaged.absolute, DevKitLockSchema);
   const currentState = yield* readOptionalStructuredFile(stateManaged.absolute, AppliedStateSchema);
+  if (
+    manifest.setup.claudeInstructions.enabled &&
+    !manifest.setup.agentInstructions.enabled &&
+    currentState?.outputs.some(
+      (output) => output.resourceId === "setup:agent-instructions",
+    )
+  ) {
+    return yield* new InvalidProjectStateError({
+      message: "cannot disable agentInstructions while claudeInstructions still links to its AGENTS.md wrapper",
+    });
+  }
   yield* validateReservedPaths(
     projectDir,
     reservedPaths,
@@ -692,7 +875,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 +920,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) {
@@ -769,7 +996,17 @@ const applyPlannedSkillChanges = Effect.fn("applyPlannedSkillChanges")(function*
     const staged = path.join(stageDir, String(stageIndex++));
     yield* fs.makeDirectory(path.dirname(staged), { recursive: true });
     if (action.desired.mode === "copy") {
-      yield* fs.copy(action.desired.source, staged, { overwrite: true });
+      if (action.desired.kind === "file") {
+        yield* fs.writeFileString(staged, action.desired.content, { mode: 0o644 });
+      } else {
+        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 +1017,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));

package/templates/AGENTS.md

@@ -0,0 +1,9 @@
+<!-- DEV KIT START -->
+
+# Dev Kit
+
+This project uses `@danieljvdm/dev-kit` to manage portable agent skills and reproducible setup from `dev-kit.jsonc` and `dev-kit.lock.json`.
+
+For dev-kit operations, use the `dev-kit` skill and read `{{DEV_KIT_SKILL_PATH}}` before changing managed outputs.
+
+<!-- DEV KIT END -->