@danieljvdm/dev-kit 0.4.0 → 0.6.0

package/src/path-digest.ts

@@ -135,6 +135,13 @@ export const digestText = Effect.fn("digestText")(function* (value: string) {
   return yield* digestFrames(["text-v1", value]);
 });
 
+export const digestFileContent = Effect.fn("digestFileContent")(function* (
+  value: string,
+  mode = 0o644,
+) {
+  return yield* digestFrames(["file-v1", String(mode), value]);
+});
+
 export const digestSymlinkTarget = Effect.fn("digestSymlinkTarget")(function* (target: string) {
   return yield* digestFrames(["symlink-v1", target]);
 });

package/src/project-package.ts

@@ -0,0 +1,34 @@
+import { Effect, FileSystem, Path, Schema } from "effect";
+
+export class ProjectPackageError extends Schema.TaggedErrorClass<ProjectPackageError>()(
+  "ProjectPackageError",
+  { message: Schema.String },
+) {}
+
+const ProjectPackageSchema = Schema.fromJsonString(Schema.Struct({
+  dependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+  devDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+  optionalDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+  peerDependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+}));
+
+export const readDirectDependencyNames = Effect.fn("readDirectDependencyNames")(function* (
+  projectDir: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const manifestPath = path.join(projectDir, "package.json");
+  if (!(yield* fs.exists(manifestPath))) return [];
+  const manifest = yield* fs.readFileString(manifestPath).pipe(
+    Effect.flatMap(Schema.decodeUnknownEffect(ProjectPackageSchema)),
+    Effect.mapError(() => new ProjectPackageError({
+      message: `invalid project package.json: ${manifestPath}`,
+    })),
+  );
+  return [...new Set([
+    ...Object.keys(manifest.dependencies ?? {}),
+    ...Object.keys(manifest.devDependencies ?? {}),
+    ...Object.keys(manifest.optionalDependencies ?? {}),
+    ...Object.keys(manifest.peerDependencies ?? {}),
+  ])].sort();
+});

package/src/project-state.ts

@@ -2,6 +2,21 @@ import { Schema } from "effect";
 
 import { DigestSchema } from "./path-digest.ts";
 
+export const CatalogProvenanceSchema = Schema.Union([
+  Schema.Struct({
+    source: Schema.String,
+    repository: Schema.String,
+    resolved: Schema.String,
+  }),
+  Schema.Struct({
+    package: Schema.String,
+    version: Schema.String,
+    skill: Schema.String,
+    digest: DigestSchema,
+  }),
+]);
+export type CatalogProvenance = typeof CatalogProvenanceSchema.Type;
+
 export const ManagedSkillOutputSchema = Schema.Struct({
   resourceId: Schema.String,
   path: Schema.String,
@@ -10,16 +25,42 @@ export const ManagedSkillOutputSchema = Schema.Struct({
   mode: Schema.Literals(["copy", "symlink"]),
   kind: Schema.Literals(["directory", "symlink"]),
   digest: DigestSchema,
-  catalog: Schema.optional(
-    Schema.Struct({
-      source: Schema.String,
-      repository: Schema.String,
-      resolved: Schema.String,
-    }),
-  ),
+  catalog: Schema.optional(CatalogProvenanceSchema),
 });
 export type ManagedSkillOutput = typeof ManagedSkillOutputSchema.Type;
 
+export const ManagedAgentInstructionsOutputSchema = Schema.Struct({
+  resourceId: Schema.Literal("setup:agent-instructions"),
+  path: Schema.String,
+  sourcePath: Schema.String,
+  mode: Schema.Literal("copy"),
+  kind: Schema.Literal("file"),
+  digest: DigestSchema,
+});
+export type ManagedAgentInstructionsOutput = typeof ManagedAgentInstructionsOutputSchema.Type;
+
+export const ManagedClaudeInstructionsOutputSchema = Schema.Struct({
+  resourceId: Schema.Literal("setup:claude-instructions"),
+  path: Schema.String,
+  sourcePath: Schema.String,
+  mode: Schema.Literal("symlink"),
+  kind: Schema.Literal("symlink"),
+  digest: DigestSchema,
+});
+export type ManagedClaudeInstructionsOutput = typeof ManagedClaudeInstructionsOutputSchema.Type;
+
+export const ManagedInstructionOutputSchema = Schema.Union([
+  ManagedAgentInstructionsOutputSchema,
+  ManagedClaudeInstructionsOutputSchema,
+]);
+export type ManagedInstructionOutput = typeof ManagedInstructionOutputSchema.Type;
+
+export const ManagedOutputSchema = Schema.Union([
+  ManagedSkillOutputSchema,
+  ManagedInstructionOutputSchema,
+]);
+export type ManagedOutput = typeof ManagedOutputSchema.Type;
+
 export const EffectTsgoLockSchema = Schema.Struct({
   effectTsgoVersion: Schema.String,
   typescriptPackage: Schema.String,
@@ -46,7 +87,7 @@ export const DevKitLockSchema = Schema.Struct({
       effectTsgo: Schema.optional(EffectTsgoLockSchema),
     }),
   ),
-  outputs: Schema.Array(ManagedSkillOutputSchema),
+  outputs: Schema.Array(ManagedOutputSchema),
 });
 export type DevKitLock = typeof DevKitLockSchema.Type;
 
@@ -54,7 +95,7 @@ export const OwnershipReceiptSchema = Schema.Struct({
   resourceId: Schema.String,
   path: Schema.String,
   mode: Schema.Literals(["copy", "symlink"]),
-  kind: Schema.Literals(["directory", "symlink"]),
+  kind: Schema.Literals(["file", "directory", "symlink"]),
   digest: DigestSchema,
 });
 export type OwnershipReceipt = typeof OwnershipReceiptSchema.Type;

package/src/skill-manager.ts

@@ -188,8 +188,14 @@ const selectedNames = (
   return selected;
 };
 
-const summary = (description: string, fallback: string): string => {
-  const text = description || fallback;
+const displayValue = (value: string): string =>
+  [...value].map((character) => {
+    const code = character.charCodeAt(0);
+    return code <= 31 || (code >= 127 && code <= 159) ? " " : character;
+  }).join("").replace(/\s+/g, " ").trim();
+
+const summary = (description: string, defaultDescription: string): string => {
+  const text = displayValue(description || defaultDescription);
   const firstSentence = text.match(/^.*?[.!?](?:\s|$)/)?.[0]?.trim() ?? text;
   return firstSentence.length > 96 ? `${firstSentence.slice(0, 93).trimEnd()}…` : firstSentence;
 };
@@ -219,15 +225,16 @@ export const addSkills = Effect.fn("addManagedSkills")(function* (
   options: ManagerOptions,
 ) {
   const current = yield* readManifest(options, true);
-  const catalog = yield* loadSkillCatalog(yield* packageRoot());
-  const known = new Set([...catalog.skills.map((skill) => skill.name), ...Object.keys(catalog.families)]);
+  const catalog = yield* loadSkillCatalog(yield* packageRoot(), current.projectDir);
+  const known = new Set([...catalog.skills.map((skill) => skill.selector), ...Object.keys(catalog.families)]);
   const unknown = names.filter((name) => !known.has(name));
   if (unknown.length > 0) {
     return yield* new SkillManagerError({
       message: `unknown skill${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}. Try \`dev-kit search ${unknown[0]}\`.`,
     });
   }
-  for (const source of catalog.lock?.sources ?? []) {
+  const sourceFamilies = catalog.lock?.sources ?? [];
+  for (const source of sourceFamilies) {
     if (!names.includes(source.id)) continue;
     yield* printStatus(
       "info",
@@ -255,7 +262,7 @@ export const removeSkills = Effect.fn("removeManagedSkills")(function* (
   options: ManagerOptions,
 ) {
   const current = yield* readManifest(options);
-  const catalog = yield* loadSkillCatalog(yield* packageRoot());
+  const catalog = yield* loadSkillCatalog(yield* packageRoot(), current.projectDir);
   const before = selectedNames(
     current.manifest.include,
     current.manifest.exclude ?? [],
@@ -287,43 +294,63 @@ export const listSkills = Effect.fn("listManagedSkills")(function* (
 ) {
   const fs = yield* FileSystem.FileSystem;
   const paths = yield* resolvePaths(options);
-  const catalog = yield* loadSkillCatalog(yield* packageRoot());
+  const catalog = yield* loadSkillCatalog(yield* packageRoot(), paths.projectDir);
   const manifest = (yield* fs.exists(paths.manifestPath))
     ? (yield* readManifest(options)).manifest
     : { include: [], exclude: [] };
   const selected = selectedNames(manifest.include, manifest.exclude ?? [], catalog.families);
   const query = options.query?.toLowerCase();
   const visible = catalog.skills.filter((skill) =>
-    (options.all || selected.has(skill.name)) &&
-    (!query || `${skill.name} ${skill.description} ${skill.source}`.toLowerCase().includes(query)),
+    (options.all || selected.has(skill.selector)) &&
+    (!query || `${skill.selector} ${skill.description} ${skill.source}`.toLowerCase().includes(query)),
+  );
+  const catalogSelectors = new Set(catalog.skills.map((skill) => skill.selector));
+  const unavailable = [...selected].filter((selector) =>
+    !catalogSelectors.has(selector) && (!query || selector.toLowerCase().includes(query))
   );
-  if (visible.length === 0) {
+  if (visible.length === 0 && unavailable.length === 0) {
     yield* printStatus("info", query ? "No matching skills" : "No skills selected");
     if (!query && !options.all) yield* printDetail("Browse with: dev-kit list --all");
     return;
   }
   for (const skill of visible) {
-    const marker = selected.has(skill.name) ? "✓" : " ";
+    const marker = selected.has(skill.selector) ? "✓" : " ";
     const origin = skill.bundled ? "built in" : skill.source;
-    const provenance = skill.bundled ? "" : ` [${skill.source}]`;
-    yield* printLine(`${marker} ${skill.name}${provenance}  ${summary(skill.description, origin)}`);
+    const provenance = skill.package
+      ? ` [installed ${displayValue(skill.package.version)}]`
+      : skill.bundled ? "" : ` [${skill.source}]`;
+    yield* printLine(`${marker} ${skill.selector}${provenance}  ${summary(skill.description, origin)}`);
+  }
+  for (const selector of unavailable) {
+    yield* printLine(`! ${selector} [unavailable]  install or repair the selected direct dependency`);
   }
   yield* printLine();
-  yield* printLine(`${selected.size} selected · ${catalog.skills.length} approved`);
+  yield* printLine(`${selected.size} selected · ${catalog.skills.length} available`);
 });
 
-export const showSkill = Effect.fn("showCatalogSkill")(function* (name: string) {
-  const catalog = yield* loadSkillCatalog(yield* packageRoot());
-  const skill = catalog.skills.find((candidate) => candidate.name === name);
+export const showSkill = Effect.fn("showCatalogSkill")(function* (
+  name: string,
+  options: ManagerOptions,
+) {
+  const paths = yield* resolvePaths(options);
+  const catalog = yield* loadSkillCatalog(yield* packageRoot(), paths.projectDir);
+  const skill = catalog.skills.find((candidate) => candidate.selector === name);
   if (!skill) return yield* new SkillManagerError({ message: `unknown skill: ${name}` });
-  yield* printLine(skill.name);
-  if (skill.description) yield* printLine(skill.description);
+  yield* printLine(skill.selector);
+  if (skill.description) yield* printLine(displayValue(skill.description));
+  if (skill.package) {
+    yield* printLine(`Source: installed package`);
+    yield* printLine(`Package: ${skill.package.name}`);
+    yield* printLine(`Version: ${displayValue(skill.package.version)}`);
+    return;
+  }
   yield* printLine(`Source: ${skill.bundled ? "dev-kit (built in)" : skill.source}`);
   if (!skill.bundled) {
     const source = catalog.lock?.sources.find((candidate) => candidate.id === skill.source);
     if (source) {
       yield* printLine(`Repository: ${source.repository}`);
       yield* printLine(`Approved commit: ${source.resolved}`);
+      return;
     }
   }
 });
@@ -345,22 +372,22 @@ export const chooseSkillsToAdd = Effect.fn("chooseSkillsToAdd")(function* (
     return yield* new SkillManagerError({ message: "pass one or more skill names, or run this command in a terminal" });
   }
   const current = yield* readManifest(options, true);
-  const catalog = yield* loadSkillCatalog(yield* packageRoot());
+  const catalog = yield* loadSkillCatalog(yield* packageRoot(), current.projectDir);
   const selected = selectedNames(
     current.manifest.include,
     current.manifest.exclude ?? [],
     catalog.families,
   );
-  const available = catalog.skills.filter((skill) => !selected.has(skill.name));
+  const available = catalog.skills.filter((skill) => !selected.has(skill.selector));
   if (available.length === 0) {
-    yield* printStatus("success", "All approved skills are selected");
+    yield* printStatus("success", "All available skills are selected");
     return;
   }
   const names = yield* Prompt.multiSelect({
     message: "Choose skills to add",
     choices: available.map((skill) => ({
-      title: skill.name,
-      value: skill.name,
+      title: skill.selector,
+      value: skill.selector,
       description: summary(skill.description, skill.source),
     })),
     min: 1,
@@ -375,7 +402,7 @@ export const chooseSkillsToRemove = Effect.fn("chooseSkillsToRemove")(function*
     return yield* new SkillManagerError({ message: "pass one or more skill names, or run this command in a terminal" });
   }
   const current = yield* readManifest(options);
-  const catalog = yield* loadSkillCatalog(yield* packageRoot());
+  const catalog = yield* loadSkillCatalog(yield* packageRoot(), current.projectDir);
   const selected = selectedNames(
     current.manifest.include,
     current.manifest.exclude ?? [],
@@ -387,11 +414,20 @@ export const chooseSkillsToRemove = Effect.fn("chooseSkillsToRemove")(function*
   }
   const names = yield* Prompt.multiSelect({
     message: "Choose skills to remove",
-    choices: catalog.skills.filter((skill) => selected.has(skill.name)).map((skill) => ({
-      title: skill.name,
-      value: skill.name,
-      description: summary(skill.description, skill.source),
-    })),
+    choices: [
+      ...catalog.skills.filter((skill) => selected.has(skill.selector)).map((skill) => ({
+        title: skill.selector,
+        value: skill.selector,
+        description: summary(skill.description, skill.source),
+      })),
+      ...[...selected]
+        .filter((selector) => !catalog.skills.some((skill) => skill.selector === selector))
+        .map((selector) => ({
+          title: selector,
+          value: selector,
+          description: "Selected but currently unavailable",
+        })),
+    ],
     min: 1,
   });
   yield* removeSkills(names, options);

package/src/skill-selector.ts

@@ -0,0 +1,43 @@
+import { isTypeScriptPackageName } from "./typescript-package-name.ts";
+
+/** An immediate Agent Skill directory name. */
+export const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+const PACKAGE_SKILL_SELECTOR_PATTERN = /^(?<package>[^#]+)#(?<skill>[^#]+)$/;
+
+type StaticSkillSelector = {
+  readonly type: "static";
+  readonly name: string;
+};
+
+type PackageSkillSelector = {
+  readonly type: "package";
+  readonly package: string;
+  readonly skill: string;
+};
+
+type SkillSelector = StaticSkillSelector | PackageSkillSelector;
+
+/**
+ * The JSON-schema-compatible pattern for static selectors and exact package
+ * selectors. Package names intentionally use the same rules as package-backed
+ * skill sources.
+ */
+export const SKILL_SELECTOR_PATTERN =
+  /^(?:[a-z0-9]+(?:-[a-z0-9]+)*|(?:[a-z0-9][a-z0-9._-]*|@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*)#[a-z0-9]+(?:-[a-z0-9]+)*)$/;
+
+export const isSkillName = (value: string): boolean => SKILL_NAME_PATTERN.test(value);
+
+/** Parse an exact, canonical manifest skill selector. */
+export const parseSkillSelector = (value: string): SkillSelector | undefined => {
+  if (isSkillName(value)) return { type: "static", name: value };
+
+  const match = PACKAGE_SKILL_SELECTOR_PATTERN.exec(value);
+  const packageName = match?.groups?.package;
+  const skill = match?.groups?.skill;
+  if (packageName === undefined || skill === undefined ||
+    !isTypeScriptPackageName(packageName) || !isSkillName(skill)) {
+    return undefined;
+  }
+  return { type: "package", package: packageName, skill };
+};