@danieljvdm/dev-kit 0.2.2 → 0.3.0

package/README.md

@@ -28,10 +28,18 @@ bun x dev-kit list --all
 bun x dev-kit add dev-kit effect
 ```
 
-Before adding external skills, scan the repository's agent instructions,
-package and lock files, framework or tool configuration, and CI workflows for
-the capabilities it actually uses. Search and inspect candidates using those
-signals, then add the matching skills individually:
+Before adding external skills, have the agent inspect repository instructions,
+workspace dependencies, framework and tool configuration, representative
+source boundaries, and CI workflows. It should compare that concrete capability
+inventory with catalog descriptions and select the narrowest useful set. Broad
+umbrella skills and source families belong only when their full breadth is
+intentional; explicit creative or advisory requests remain valid even without a
+mechanical dependency signal. Treat lazy reference folders inside one skill as
+progressive-disclosure content, not as separately triggered skills; a repository
+using several covered products may reasonably select that umbrella while still
+excluding unrelated top-level skills.
+
+Search and inspect candidates, then add the matching skills individually:
 
 ```bash
 bun x dev-kit search cloudflare
@@ -301,6 +309,28 @@ transforms, and installs the result through the ownership-safe sync path. Normal
 installs never float to a newer upstream commit; only a reviewed catalog refresh
 changes what is approved.
 
+## Oxlint preset for Vite+
+
+Dev Kit exports a typed, composable set of high-signal Oxlint rules for Vite+
+projects:
+
+```ts
+import { recommendedOxlintConfig } from "@danieljvdm/dev-kit/oxlint";
+import { defineConfig } from "vite-plus";
+
+export default defineConfig({
+  lint: {
+    extends: [recommendedOxlintConfig],
+    rules: {
+      // Add repository-specific rules here.
+    },
+  },
+});
+```
+
+Use `lint.extends` rather than a shallow object spread so Vite+ composes the
+nested plugin and rule configuration correctly.
+
 ## Development
 
 ```bash

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@danieljvdm/dev-kit",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "description": "Declarative project development toolkit with portable agent skills.",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/danieljvdm/agent-skills.git"
+    "url": "git+https://github.com/danieljvdm/dev-kit.git"
   },
   "license": "MIT",
   "bin": {
@@ -19,7 +19,11 @@
     },
     "./schema": "./schema/dev-kit.schema.json",
     "./schema/dev-kit.schema.json": "./schema/dev-kit.schema.json",
-    "./schema/skill-sources.schema.json": "./schema/skill-sources.schema.json"
+    "./schema/skill-sources.schema.json": "./schema/skill-sources.schema.json",
+    "./oxlint": {
+      "types": "./src/oxlint.ts",
+      "default": "./src/oxlint.ts"
+    }
   },
   "files": [
     "dev-kit.example.jsonc",
@@ -36,7 +40,8 @@
     "changeset": "changeset",
     "version-packages": "changeset version && ./bin/dev-kit.mjs apply",
     "release": "changeset publish",
-    "check": "tsc --noEmit",
+    "check": "tsc --noEmit && vp lint",
+    "lint": "vp lint",
     "plan": "./bin/dev-kit.mjs plan",
     "apply": "./bin/dev-kit.mjs apply",
     "gitignore": "./bin/dev-kit.mjs gitignore",
@@ -60,8 +65,17 @@
     "@effect/vitest": "4.0.0-beta.102",
     "@types/node": "25.9.1",
     "typescript": "7.0.2",
+    "vite-plus": "0.2.6",
     "vitest": "4.1.10"
   },
+  "peerDependencies": {
+    "vite-plus": ">=0.2.6 <0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "vite-plus": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=22.12.0"
   },

package/schema/dev-kit.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://raw.githubusercontent.com/danieljvdm/agent-skills/main/schema/dev-kit.schema.json",
+  "$id": "https://raw.githubusercontent.com/danieljvdm/dev-kit/main/schema/dev-kit.schema.json",
   "title": "Dev Kit Manifest",
   "description": "Project-local desired state for portable skills and explicit dev-kit setup tasks.",
   "type": "object",

package/schema/skill-sources.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://raw.githubusercontent.com/danieljvdm/agent-skills/main/schema/skill-sources.schema.json",
+  "$id": "https://raw.githubusercontent.com/danieljvdm/dev-kit/main/schema/skill-sources.schema.json",
   "title": "External Agent Skill Sources",
   "description": "Repository-level sources approved for the skill catalog.",
   "type": "object",

package/skills/dev-kit/SKILL.md

@@ -21,23 +21,37 @@ stores explicit skill names and exact commit/content digests.
 
 ## Apply loop
 
-1. Establish the Git root. Read project agent instructions, `dev-kit.jsonc`,
-   `dev-kit.lock.json` when present, package and lock files, framework or tool
-   configuration, CI workflows, and the configured target paths. Derive the
-   capabilities the project actually uses from those signals.
-2. Use `dev-kit search <terms>` and `dev-kit info <skill>` to inspect matching
-   catalog entries. Prefer individual external skills; select an external
-   source family only when every approved skill from it applies. Update
-   `dev-kit.jsonc`, preserve JSONC comments, and validate against the package
-   schema. Finish with each desired resource represented once.
-3. Run `dev-kit plan`. Use `--manifest`, `--project-dir`, or `--lockfile` when
+1. Establish the Git root. Read project agent instructions, the current
+   manifest and lock, package and workspace manifests, framework and tool
+   configuration, representative source boundaries, and CI workflows. Build a
+   concrete inventory of the platforms, frameworks, tools, and workflows the
+   repository actually uses; do not infer capabilities from a product or
+   company name alone.
+2. Run `dev-kit list --all`, then use `dev-kit search <terms>` and `dev-kit info
+   <skill>` for each capability in the inventory. Compare every candidate's
+   trigger description with concrete repository evidence. Keep explicitly
+   requested creative or advisory skills even when they have no mechanical
+   dependency signal.
+3. Choose the narrowest useful set. Prefer focused external skills over a
+   generic umbrella when they cover the repository's work. Select an umbrella
+   or external source family only when its full breadth is intentionally useful;
+   never select one merely because one member or product matches. Explain any
+   uncertain inclusion before applying it. Distinguish separately triggered
+   skills from lazy `references/` bundled inside one skill: unused reference
+   folders cost repository space but are not loaded into agent context unless
+   the skill routes to them. A multi-product repository can therefore justify
+   an umbrella while still excluding unrelated top-level skills.
+4. Update `dev-kit.jsonc`. Preserve JSONC comments and validate against the
+   package schema. Finish with each desired resource represented once and every
+   external selection supported by repository evidence or an explicit request.
+5. Run `dev-kit plan`. Use `--manifest`, `--project-dir`, or `--lockfile` when
    the project overrides their defaults. Planning is read-only; inspect every
    create, update, remove, adoption, and conflict before proceeding. Finish
    when the plan contains only intended actions and understood conflicts.
-4. Resolve conflicts, then run `dev-kit apply`. Commit the manifest and
+6. Resolve conflicts, then run `dev-kit apply`. Commit the manifest and
    regenerated `dev-kit.lock.json`; keep `.dev-kit/` local. Finish when a second
    plan reports only unchanged resources and setup tasks.
-5. Use `dev-kit apply --locked` in CI and the package lifecycle. Finish when a
+7. Use `dev-kit apply --locked` in CI and the package lifecycle. Finish when a
    clean install converges from the committed manifest and lock.
 
 ## Manifest
@@ -142,10 +156,34 @@ dependencies; `dev-kit apply` patches once and then converges.
 Use `dev-kit tsgo patch --dry-run` for focused diagnosis. Use `--force` only
 after the user accepts a potentially commit-incompatible TypeScript binary.
 
+## Oxlint preset for Vite+
+
+For Vite+ projects, compose the package's typed recommended Oxlint preset with
+project-specific lint configuration:
+
+```ts
+import { recommendedOxlintConfig } from "@danieljvdm/dev-kit/oxlint";
+import { defineConfig } from "vite-plus";
+
+export default defineConfig({
+  lint: {
+    extends: [recommendedOxlintConfig],
+    rules: {
+      // Project-specific rules apply after the shared preset.
+    },
+  },
+});
+```
+
+Use `lint.extends` instead of spreading the object so Vite+ composes nested
+rule maps correctly. Keep repository-specific path conventions and
+platform-specific accessibility rules in the consuming project.
+
 ## Current boundary
 
 Manage skill outputs, the `setup.effectSource` checkout, and the explicit
 `setup.effectTsgo` task. Edit shared `package.json` and `tsconfig.json`
-contributions deliberately. Treat named bundles, Oxlint/Oxfmt presets, and
-broader setup tasks as future manifest capabilities until the installed CLI
-exposes them.
+contributions deliberately. The Oxlint preset is a composable package export,
+not a manifest-managed output. Treat named bundles, Oxfmt presets, and broader
+setup tasks as future manifest capabilities until the installed CLI exposes
+them.

package/src/catalog-manager.ts

@@ -216,7 +216,10 @@ export const addCatalogSource = Effect.fn("addCatalogSource")(function* (
   const existingIndex = byId >= 0 ? byId : byRepository;
   let next = state.sources.raw;
   if (existingIndex >= 0) {
-    const existing = sources[existingIndex]!;
+    const existing = sources[existingIndex];
+    if (existing === undefined) {
+      return yield* new CatalogManagerError({ message: "catalog source index is out of bounds" });
+    }
     const approved = state.lock?.value.sources.find((source) => source.id === existing.id)?.skills ?? [];
     const currentInclude = existing.include.includes("*") ? approved : existing.include;
     const include = [...new Set([...currentInclude, ...selection.include])].sort();

package/src/gitignore.ts

@@ -1,4 +1,4 @@
-import { Cause, Effect, FileSystem, Path, PlatformError, Schema } from "effect";
+import { Cause, Effect, FileSystem, Path, type PlatformError, Schema } from "effect";
 
 import { printStatus } from "./cli-ui.ts";
 import { observeSymbolicLink } from "./node-symbolic-link.ts";

package/src/node-symbolic-link.ts

@@ -1,4 +1,4 @@
-import { Effect, FileSystem, PlatformError } from "effect";
+import { Effect, FileSystem, type PlatformError } from "effect";
 
 export type SymbolicLinkObservation =
   | { readonly kind: "missing" | "not-symlink" }

package/src/oxlint.ts

@@ -0,0 +1,35 @@
+import type { OxlintConfig } from "vite-plus/lint";
+
+/**
+ * High-signal Oxlint defaults for TypeScript projects using Vite+.
+ *
+ * Extend this object from `lint.extends` so project-local plugins, rules, and
+ * overrides compose without losing nested configuration.
+ */
+export const recommendedOxlintConfig = {
+  options: {
+    typeAware: true,
+  },
+  plugins: ["import", "react", "vitest"],
+  rules: {
+    eqeqeq: "error",
+    "import/default": "off",
+    "import/namespace": "off",
+    "import/no-cycle": "error",
+    "import/no-duplicates": "error",
+    "import/no-self-import": "error",
+    "react/exhaustive-deps": "error",
+    "react/rules-of-hooks": "error",
+    "typescript/consistent-type-imports": "error",
+    "typescript/no-explicit-any": "error",
+    "typescript/no-non-null-assertion": "error",
+    "typescript/switch-exhaustiveness-check": "error",
+    "unicorn/prefer-node-protocol": "error",
+    "vitest/no-focused-tests": "error",
+    "vitest/no-identical-title": "error",
+    "vitest/no-standalone-expect": "off",
+    "vitest/valid-expect": "error",
+  },
+} satisfies OxlintConfig;
+
+export type RecommendedOxlintConfig = typeof recommendedOxlintConfig;

package/src/path-digest.ts

@@ -1,4 +1,4 @@
-import { Crypto, Effect, Encoding, FileSystem, Path, PlatformError, Schema } from "effect";
+import { Crypto, Effect, Encoding, FileSystem, Path, type PlatformError, Schema } from "effect";
 
 import { observeSymbolicLink } from "./node-symbolic-link.ts";
 

package/src/skill-manager.ts

@@ -154,7 +154,8 @@ const writeArray = Effect.fn("writeManifestArray")(function* (
   let next = raw;
   const retained = [...current];
   for (let index = current.length - 1; index >= 0; index -= 1) {
-    if (!values.includes(current[index]!)) {
+    const currentValue = current[index];
+    if (currentValue !== undefined && !values.includes(currentValue)) {
       next = applyEdits(next, modify(next, [property, index], undefined, {
         formattingOptions: { insertSpaces: true, tabSize: 2 },
       }));

package/src/sync.ts

@@ -284,7 +284,6 @@ const resolveManagedPath = Effect.fn("resolveManagedPath")(function* (
   projectDir: string,
   candidate: string,
 ) {
-  const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
   if (candidate.length === 0 || path.isAbsolute(candidate)) {
     return yield* new UnsafeManagedPathError({ path: candidate, reason: "must be a non-empty project-relative path" });

package/src/vendor.ts

@@ -109,6 +109,14 @@ const inferSourceId = (repository: string): string => {
   return tail.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 };
 
+const containsControlCharacter = (value: string): boolean => {
+  for (const character of value) {
+    const code = character.charCodeAt(0);
+    if (code <= 0x1f || code === 0x7f) return true;
+  }
+  return false;
+};
+
 const normalizeRepositoryLocator = (
   repository: string,
 ): Effect.Effect<{
@@ -116,7 +124,7 @@ const normalizeRepositoryLocator = (
   readonly ref?: string;
   readonly skillsPath?: string;
 }, InvalidSourceError> => {
-  if (/[\u0000-\u001f\u007f]/.test(repository)) {
+  if (containsControlCharacter(repository)) {
     return Effect.fail(new InvalidSourceError({ source: repository, reason: "repository contains control characters" }));
   }
   try {
@@ -126,9 +134,9 @@ const normalizeRepositoryLocator = (
     }
     if (url.hostname.toLowerCase() !== "github.com") return Effect.succeed({ repository });
     const segments = url.pathname.split("/").filter(Boolean).map(decodeURIComponent);
-    if (segments.length < 2) return Effect.succeed({ repository });
-    const owner = segments[0]!;
-    const name = segments[1]!.replace(/\.git$/i, "");
+    const [owner, rawName] = segments;
+    if (owner === undefined || rawName === undefined) return Effect.succeed({ repository });
+    const name = rawName.replace(/\.git$/i, "");
     const normalized = `https://github.com/${owner}/${name}.git`;
     if (segments[2] === "tree" && segments[3]) {
       return Effect.succeed({
@@ -389,13 +397,20 @@ const prepareSource = Effect.fn("prepareSkillSource")(function* (
   yield* fs.makeDirectory(checkoutDir, { recursive: true });
   yield* runCommand(checkoutDir, "git", ["init", "--quiet"]);
   yield* runCommand(checkoutDir, "git", ["remote", "add", "origin", source.repository]);
+  const fetchRef = useLock ? lockedSource?.resolved : source.ref;
+  if (fetchRef === undefined) {
+    return yield* new InvalidSourceError({
+      source: source.id,
+      reason: "no matching lockfile entry; run catalog refresh without --locked first",
+    });
+  }
   yield* runCommand(checkoutDir, "git", [
     "fetch",
     "--quiet",
     "--depth",
     "1",
     "origin",
-    useLock ? lockedSource!.resolved : source.ref,
+    fetchRef,
   ]);
   yield* runCommand(checkoutDir, "git", ["checkout", "--quiet", "--detach", "FETCH_HEAD"]);
   const resolved = yield* runCommand(checkoutDir, "git", ["rev-parse", "HEAD"]);