@danieljvdm/dev-kit 0.11.3 → 0.12.0

package/src/catalog-manager.ts

@@ -36,10 +36,9 @@ export type CatalogAddOptions = CatalogCommandOptions & {
   readonly dryRun?: boolean;
 };
 
-class CatalogManagerError extends Schema.TaggedErrorClass<CatalogManagerError>()(
-  "CatalogManagerError",
-  { message: Schema.String },
-) {}
+class CatalogManagerError extends Schema.TaggedError<CatalogManagerError>()("CatalogManagerError", {
+  message: Schema.String,
+}) {}
 
 const formattingOptions = { insertSpaces: true, tabSize: 2 } as const;
 
@@ -63,17 +62,17 @@ const readJsonc = Effect.fn("readCatalogManagerJsonc")(function* <A>(
   const fs = yield* FileSystem.FileSystem;
 
   if (!(yield* fs.exists(filePath))) {
-    return yield* new CatalogManagerError({ message: `file not found: ${filePath}` });
+    return yield* CatalogManagerError.make({ message: `file not found: ${filePath}` });
   }
   const raw = yield* fs.readFileString(filePath);
   const errors: Array<ParseError> = [];
   const parsed = parseJsonc(raw, errors, { allowTrailingComma: true });
 
   if (errors.length > 0) {
-    return yield* new CatalogManagerError({ message: `could not parse ${filePath}` });
+    return yield* CatalogManagerError.make({ message: `could not parse ${filePath}` });
   }
   const value = yield* Schema.decodeUnknownEffect(schema)(parsed).pipe(
-    Effect.mapError((error) => new CatalogManagerError({ message: error.message })),
+    Effect.mapError((error) => CatalogManagerError.make({ message: error.message })),
   );
 
   return { raw, value };
@@ -105,7 +104,7 @@ const selectSkills = Effect.fn("selectCatalogSkills")(function* (
   const unknown = requested.filter((skill) => !available.has(skill));
 
   if (unknown.length > 0) {
-    return yield* new CatalogManagerError({
+    return yield* CatalogManagerError.make({
       message: `repository does not contain: ${unknown.join(", ")}`,
     });
   }
@@ -117,7 +116,7 @@ const selectSkills = Effect.fn("selectCatalogSkills")(function* (
   if (requested.length > 0)
     return { include: [...new Set(requested)], selected: [...new Set(requested)] };
   if (!(yield* isInteractiveTerminal)) {
-    return yield* new CatalogManagerError({
+    return yield* CatalogManagerError.make({
       message: "choose skills with --skill <name>, or pass --all",
     });
   }
@@ -194,7 +193,7 @@ export const addCatalogSource = Effect.fn("addCatalogSource")(function* (
   options: CatalogAddOptions,
 ) {
   if (options.all && (options.skills?.length ?? 0) > 0) {
-    return yield* new CatalogManagerError({ message: "use either --all or --skill, not both" });
+    return yield* CatalogManagerError.make({ message: "use either --all or --skill, not both" });
   }
   const state = yield* readState(options);
   const inspection = yield* inspectCatalogRepository({
@@ -210,12 +209,12 @@ export const addCatalogSource = Effect.fn("addCatalogSource")(function* (
   const byRepository = sources.findIndex((source) => source.repository === inspection.repository);
 
   if (byId >= 0 && sources[byId]?.repository !== inspection.repository) {
-    return yield* new CatalogManagerError({
+    return yield* CatalogManagerError.make({
       message: `source id ${inspection.id} is already used by ${sources[byId]?.repository}`,
     });
   }
   if (byRepository >= 0 && sources[byRepository]?.id !== inspection.id) {
-    return yield* new CatalogManagerError({
+    return yield* CatalogManagerError.make({
       message: `repository is already cataloged as ${sources[byRepository]?.id}`,
     });
   }
@@ -226,7 +225,7 @@ export const addCatalogSource = Effect.fn("addCatalogSource")(function* (
     const existing = sources[existingIndex];
 
     if (existing === undefined) {
-      return yield* new CatalogManagerError({ message: "catalog source index is out of bounds" });
+      return yield* CatalogManagerError.make({ message: "catalog source index is out of bounds" });
     }
     const approved =
       state.lock?.value.sources.find((source) => source.id === existing.id)?.skills ?? [];
@@ -308,12 +307,12 @@ export const removeCatalogEntry = Effect.fn("removeCatalogEntry")(function* (
     const owner = state.lock?.value.sources.find((source) => source.skills.includes(name));
 
     if (!owner)
-      return yield* new CatalogManagerError({ message: `catalog entry not found: ${name}` });
+      return yield* CatalogManagerError.make({ message: `catalog entry not found: ${name}` });
     const index = sources.findIndex((source) => source.id === owner.id);
     const source = sources[index];
 
     if (!source)
-      return yield* new CatalogManagerError({ message: `source not found: ${owner.id}` });
+      return yield* CatalogManagerError.make({ message: `source not found: ${owner.id}` });
     if (source.include.includes("*")) {
       const exclude = [...new Set([...(source.exclude ?? []), name])];
 
@@ -342,7 +341,7 @@ export const removeCatalogEntry = Effect.fn("removeCatalogEntry")(function* (
   }
   if (!options.yes) {
     if (!(yield* isInteractiveTerminal)) {
-      return yield* new CatalogManagerError({
+      return yield* CatalogManagerError.make({
         message: "catalog removal requires --yes outside a terminal",
       });
     }
@@ -388,7 +387,7 @@ export const showCatalogSource = Effect.fn("showCatalogSource")(function* (
   const source = state.sources.value.sources.find((candidate) => candidate.id === id);
 
   if (!source)
-    return yield* new CatalogManagerError({ message: `catalog source not found: ${id}` });
+    return yield* CatalogManagerError.make({ message: `catalog source not found: ${id}` });
   const locked = state.lock?.value.sources.find((candidate) => candidate.id === id);
 
   yield* printLine(source.id);

package/src/catalog.ts

@@ -2,8 +2,13 @@ import { Effect, FileSystem, Path, Schema, Stream } from "effect";
 import { ChildProcess } from "effect/unstable/process";
 import { parse as parseJsonc, type ParseError } from "jsonc-parser";
 
-import { discoverPackageSkills, resolvePackageSkillSelector } from "./package-skill-source.ts";
+import {
+  discoverPackageSkills,
+  resolvePackageSkillSelector,
+  type DiscoveredPackageSkill,
+} from "./package-skill-source.ts";
 import { observePath, type Digest } from "./path-digest.ts";
+import { packageSkillInstallName } from "./skill-selector.ts";
 import {
   SkillSourcesLockSchema,
   type LockedSkillSource,
@@ -45,7 +50,7 @@ export type ResolvedSkillSource = {
       };
 };
 
-class CatalogError extends Schema.TaggedErrorClass<CatalogError>()("CatalogError", {
+class CatalogError extends Schema.TaggedError<CatalogError>()("CatalogError", {
   message: Schema.String,
 }) {}
 
@@ -61,7 +66,7 @@ const runGit = Effect.fn("runCatalogGit")(function* (cwd: string, args: Readonly
   ]);
 
   if (exitCode !== 0) {
-    return yield* new CatalogError({
+    return yield* CatalogError.make({
       message: `git ${args.join(" ")} failed: ${output.trim()}`,
     });
   }
@@ -80,11 +85,11 @@ const readCatalogLock = Effect.fn("readCatalogLock")(function* (packageRoot: str
   const value = parseJsonc(raw, errors, { allowTrailingComma: true });
 
   if (errors.length > 0) {
-    return yield* new CatalogError({ message: `invalid skill catalog lock: ${lockPath}` });
+    return yield* CatalogError.make({ message: `invalid skill catalog lock: ${lockPath}` });
   }
 
   return yield* Schema.decodeUnknownEffect(SkillSourcesLockSchema)(value).pipe(
-    Effect.mapError((error) => new CatalogError({ message: error.message })),
+    Effect.mapError((error) => CatalogError.make({ message: error.message })),
   );
 });
 
@@ -145,7 +150,7 @@ export const loadSkillCatalog = Effect.fn("loadSkillCatalog")(function* (
 
   for (const candidate of discovery.candidates) {
     skills.push({
-      name: candidate.name,
+      name: packageSkillInstallName(candidate.package, candidate.name),
       selector: candidate.selector,
       description: candidate.description,
       source: candidate.package,
@@ -159,7 +164,7 @@ export const loadSkillCatalog = Effect.fn("loadSkillCatalog")(function* (
   );
 
   if (duplicates.length > 0) {
-    return yield* new CatalogError({
+    return yield* CatalogError.make({
       message: `duplicate catalog skill selector: ${duplicates[0]?.selector ?? "unknown"}`,
     });
   }
@@ -171,13 +176,12 @@ export const loadSkillCatalog = Effect.fn("loadSkillCatalog")(function* (
   );
 
   if (duplicateFamily !== undefined) {
-    return yield* new CatalogError({
+    return yield* CatalogError.make({
       message: `duplicate catalog family: ${duplicateFamily[0]}`,
     });
   }
   const families: Readonly<Record<string, ReadonlyArray<string>>> = {
-    effect: ["effect-ts"],
-    "effect-atom-data-fetching": ["effect-ts"],
+    effect: ["effect-ts", "effect-architecture-audit", "build-effect-apis"],
     ...Object.fromEntries(externalFamilies),
   };
 
@@ -206,6 +210,57 @@ const stripFrontmatterKeys = (text: string, keys: ReadonlyArray<string>): string
   return `---\n${lines.join("\n")}\n---${frontmatter[2]}${text.slice(frontmatter[0].length)}`;
 };
 
+const rewriteFrontmatterName = (text: string, name: string): string => {
+  const frontmatter = text.match(/^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/);
+
+  if (!frontmatter?.[1]) return text;
+  let replacing = false;
+  const lines = frontmatter[1].split(/\r?\n/).flatMap((line) => {
+    const key = line.match(/^([A-Za-z0-9_-]+):/)?.[1];
+
+    if (key !== undefined) replacing = key === "name";
+
+    return replacing ? (key === undefined ? [] : [`name: ${name}`]) : [line];
+  });
+
+  return `---\n${lines.join("\n")}\n---${frontmatter[2]}${text.slice(frontmatter[0].length)}`;
+};
+
+const materializePackageSkill = Effect.fn("materializePackageSkill")(function* (
+  projectDir: string,
+  skill: DiscoveredPackageSkill,
+  digest: Digest,
+  cache: boolean,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const installName = packageSkillInstallName(skill.package, skill.name);
+  const root = cache
+    ? path.join(projectDir, ".dev-kit", "cache", "package-skills", installName)
+    : path.join(
+        yield* fs.makeTempDirectoryScoped({ prefix: "dev-kit-package-plan-" }),
+        installName,
+      );
+  const staged = path.join(root, "skill");
+  const ready = path.join(root, ".ready");
+  const stamp = `${skill.version}\n${digest}\n`;
+
+  if (!(yield* fs.exists(ready)) || (yield* fs.readFileString(ready)) !== stamp) {
+    yield* fs.remove(root, { force: true, recursive: true });
+    yield* fs.makeDirectory(root, { recursive: true });
+    yield* fs.copy(skill.path, staged, { overwrite: true });
+    const document = path.join(staged, "SKILL.md");
+
+    yield* fs.writeFileString(
+      document,
+      rewriteFrontmatterName(yield* fs.readFileString(document), installName),
+    );
+    yield* fs.writeFileString(ready, stamp);
+  }
+
+  return staged;
+});
+
 const materializeSource = Effect.fn("materializeCatalogSource")(function* (
   projectDir: string,
   source: LockedSkillSource,
@@ -234,14 +289,14 @@ const materializeSource = Effect.fn("materializeCatalogSource")(function* (
     const actual = yield* runGit(checkout, ["rev-parse", "HEAD"]);
 
     if (actual !== source.resolved) {
-      return yield* new CatalogError({
+      return yield* CatalogError.make({
         message: `source ${source.id} resolved to ${actual}, expected ${source.resolved}`,
       });
     }
     const symlinks = yield* runGit(checkout, ["ls-files", "--stage", "--", source.skillsPath]);
 
     if (symlinks.split(/\r?\n/).some((line) => line.startsWith("120000 "))) {
-      return yield* new CatalogError({
+      return yield* CatalogError.make({
         message: `source ${source.id} contains symlinks; refusing to install it`,
       });
     }
@@ -251,7 +306,7 @@ const materializeSource = Effect.fn("materializeCatalogSource")(function* (
       const observation = yield* observePath(from);
 
       if (observation.kind !== "directory") {
-        return yield* new CatalogError({
+        return yield* CatalogError.make({
           message: `source ${source.id} is missing skill ${skill}`,
         });
       }
@@ -275,7 +330,7 @@ const materializeSource = Effect.fn("materializeCatalogSource")(function* (
       approvedDigest !== undefined &&
       (observation.kind !== "directory" || observation.digest !== approvedDigest)
     ) {
-      return yield* new CatalogError({
+      return yield* CatalogError.make({
         message: `cached skill ${skill} does not match the approved catalog; remove ${root} and retry`,
       });
     }
@@ -324,10 +379,10 @@ export const resolveSkillSources = Effect.fn("resolveSkillSources")(function* (
     const observation = yield* observePath(resolved.path);
 
     if (observation.kind !== "directory") {
-      return yield* new CatalogError({ message: `package skill is missing: ${selector}` });
+      return yield* CatalogError.make({ message: `package skill is missing: ${selector}` });
     }
     sources.set(selector, {
-      path: resolved.path,
+      path: yield* materializePackageSkill(projectDir, resolved, observation.digest, cache),
       linkPath: resolved.linkPath,
       catalog: {
         package: resolved.package,

package/src/effect-source.ts

@@ -28,7 +28,20 @@ export type EffectSourcePlan = {
   readonly tag: string;
 };
 
-export class EffectSourceDependencyError extends Schema.TaggedErrorClass<EffectSourceDependencyError>()(
+const EffectSourcePlanJsonSchema = Schema.fromJsonString(
+  Schema.Struct({
+    action: Schema.Literals(["sync", "unchanged", "skipped"]),
+    checkoutDir: Schema.String,
+    packageName: Schema.String,
+    packageVersion: Schema.String,
+    path: Schema.String,
+    projectDir: Schema.String,
+    repository: Schema.String,
+    tag: Schema.String,
+  }),
+);
+
+export class EffectSourceDependencyError extends Schema.TaggedError<EffectSourceDependencyError>()(
   "EffectSourceDependencyError",
   { packageName: Schema.String },
 ) {
@@ -37,12 +50,12 @@ export class EffectSourceDependencyError extends Schema.TaggedErrorClass<EffectS
   }
 }
 
-export class EffectSourceCheckoutError extends Schema.TaggedErrorClass<EffectSourceCheckoutError>()(
+export class EffectSourceCheckoutError extends Schema.TaggedError<EffectSourceCheckoutError>()(
   "EffectSourceCheckoutError",
   { message: Schema.String },
 ) {}
 
-class EffectSourceCommandError extends Schema.TaggedErrorClass<EffectSourceCommandError>()(
+class EffectSourceCommandError extends Schema.TaggedError<EffectSourceCommandError>()(
   "EffectSourceCommandError",
   { command: Schema.String, exitCode: Schema.Int, output: Schema.String },
 ) {
@@ -76,7 +89,7 @@ const runCommand = Effect.fn("runEffectSourceCommand")(function* (
   const trimmed = output.trim();
 
   if (exitCode !== 0) {
-    return yield* new EffectSourceCommandError({
+    return yield* EffectSourceCommandError.make({
       command: [command, ...args].join(" "),
       exitCode,
       output: trimmed,
@@ -104,12 +117,12 @@ const readPackageVersion = Effect.fn("readEffectSourcePackageVersion")(function*
     .readFileString(manifestPath)
     .pipe(
       Effect.catchReason("PlatformError", "NotFound", () =>
-        Effect.fail(new EffectSourceDependencyError({ packageName })),
+        Effect.fail(EffectSourceDependencyError.make({ packageName })),
       ),
     );
 
-  return yield* Schema.decodeUnknownEffect(PackageVersionSchema)(contents).pipe(
-    Effect.mapError(() => new EffectSourceDependencyError({ packageName })),
+  return yield* Schema.decodeEffect(PackageVersionSchema)(contents).pipe(
+    Effect.mapError(() => EffectSourceDependencyError.make({ packageName })),
     Effect.map((manifest) => manifest.version),
   );
 });
@@ -121,7 +134,7 @@ const resolveCheckoutPath = Effect.fn("resolveEffectSourceCheckoutPath")(functio
   const path = yield* Path.Path;
 
   if (candidate.length === 0 || path.isAbsolute(candidate)) {
-    return yield* new EffectSourceCheckoutError({
+    return yield* EffectSourceCheckoutError.make({
       message: `Effect source path must be a non-empty project-relative path: ${candidate}`,
     });
   }
@@ -134,7 +147,7 @@ const resolveCheckoutPath = Effect.fn("resolveEffectSourceCheckoutPath")(functio
     relative.startsWith(`..${path.sep}`) ||
     path.isAbsolute(relative)
   ) {
-    return yield* new EffectSourceCheckoutError({
+    return yield* EffectSourceCheckoutError.make({
       message: `Effect source path resolves outside the project: ${candidate}`,
     });
   }
@@ -143,7 +156,7 @@ const resolveCheckoutPath = Effect.fn("resolveEffectSourceCheckoutPath")(functio
   for (const segment of relative.split(path.sep).slice(0, -1)) {
     ancestor = path.join(ancestor, segment);
     if ((yield* observeSymbolicLink(ancestor)).kind === "symlink") {
-      return yield* new EffectSourceCheckoutError({
+      return yield* EffectSourceCheckoutError.make({
         message: `Effect source path has a symlink ancestor: ${ancestor}`,
       });
     }
@@ -163,31 +176,30 @@ const inspectExistingCheckout = Effect.fn("inspectExistingEffectSource")(functio
   const fs = yield* FileSystem.FileSystem;
 
   if ((yield* observeSymbolicLink(checkoutDir)).kind === "symlink") {
-    return yield* new EffectSourceCheckoutError({
+    return yield* EffectSourceCheckoutError.make({
       message: `Effect source destination is a symlink: ${checkoutDir}`,
     });
   }
   if (!(yield* fs.exists(checkoutDir))) return "sync" as const;
 
   const actualRoot = yield* runGit(checkoutDir, ["rev-parse", "--show-toplevel"]).pipe(
-    Effect.mapError(
-      () =>
-        new EffectSourceCheckoutError({
-          message: `Effect source destination exists but is not a Git checkout: ${checkoutDir}`,
-        }),
+    Effect.mapError(() =>
+      EffectSourceCheckoutError.make({
+        message: `Effect source destination exists but is not a Git checkout: ${checkoutDir}`,
+      }),
     ),
   );
   const expectedRoot = yield* fs.realPath(checkoutDir);
 
   if ((yield* fs.realPath(actualRoot)) !== expectedRoot) {
-    return yield* new EffectSourceCheckoutError({
+    return yield* EffectSourceCheckoutError.make({
       message: `Effect source destination is nested inside another Git checkout: ${checkoutDir}`,
     });
   }
   const remote = yield* runGit(checkoutDir, ["remote", "get-url", "origin"]);
 
   if (remote !== repository) {
-    return yield* new EffectSourceCheckoutError({
+    return yield* EffectSourceCheckoutError.make({
       message: `Effect source origin is ${remote}; expected ${repository}`,
     });
   }
@@ -208,7 +220,7 @@ const inspectExistingCheckout = Effect.fn("inspectExistingEffectSource")(functio
   const dirty = yield* runGit(checkoutDir, ["status", "--porcelain", "--untracked-files=all"]);
 
   if (dirty.length > 0) {
-    return yield* new EffectSourceCheckoutError({
+    return yield* EffectSourceCheckoutError.make({
       message: `Effect source checkout has local changes; refusing to switch ${checkoutDir} to ${tag}`,
     });
   }
@@ -225,14 +237,14 @@ export const planEffectSource = Effect.fn("planEffectSource")(function* (
   const packageName = options.packageName ?? "effect";
 
   if (!isTypeScriptPackageName(packageName)) {
-    return yield* new EffectSourceCheckoutError({
+    return yield* EffectSourceCheckoutError.make({
       message: `invalid Effect source package name: ${packageName}`,
     });
   }
   const repository = options.repository ?? DEFAULT_EFFECT_REPOSITORY;
 
   if (repository.length === 0) {
-    return yield* new EffectSourceCheckoutError({
+    return yield* EffectSourceCheckoutError.make({
       message: "Effect source repository cannot be empty",
     });
   }
@@ -289,7 +301,7 @@ export const applyEffectSourcePlan = Effect.fn("applyEffectSourcePlan")(function
       staged,
     ]);
     if (yield* fs.exists(plan.checkoutDir)) {
-      return yield* new EffectSourceCheckoutError({
+      return yield* EffectSourceCheckoutError.make({
         message: `Effect source destination appeared while cloning: ${plan.checkoutDir}`,
       });
     }
@@ -344,9 +356,19 @@ export const syncEffectSource = Effect.fn("syncEffectSource")(function* (
   }
   yield* acquireProjectProcessLock(plan.projectDir);
   const replanned = yield* planEffectSource(options);
+  const [plannedSignature, replannedSignature] = yield* Effect.all([
+    Schema.encodeEffect(EffectSourcePlanJsonSchema)(plan),
+    Schema.encodeEffect(EffectSourcePlanJsonSchema)(replanned),
+  ]).pipe(
+    Effect.mapError((error) =>
+      EffectSourceCheckoutError.make({
+        message: `could not encode Effect source plan: ${error.message}`,
+      }),
+    ),
+  );
 
-  if (JSON.stringify(plan) !== JSON.stringify(replanned)) {
-    return yield* new EffectSourceCheckoutError({
+  if (plannedSignature !== replannedSignature) {
+    return yield* EffectSourceCheckoutError.make({
       message: "Effect source checkout changed after planning; rerun the command",
     });
   }