@danieljvdm/dev-kit 0.7.0 → 0.7.2

package/README.md

@@ -277,16 +277,79 @@ quality configuration and GitHub Actions workflow:
 
 The quality task requires direct `@danieljvdm/dev-kit`, `vite-plus`, `effect`,
 `@effect/tsgo`, and native TypeScript dependencies, plus the enabled Effect
-TypeScript-Go patch. It manages `vite.config.ts` and
+TypeScript-Go patch. The installed Vite+ version must satisfy Dev Kit's
+`vite-plus` peer range; Dev Kit tests one exact development version inside that
+range, while CI lets `setup-vp` resolve the consumer's version from its own
+manifest and lockfile. It manages `vite.config.ts` and
 `.github/workflows/check.yml` as digest-owned files. Existing custom files or
 conflicting `check`/`typecheck` package scripts are rejected instead of merged
 or overwritten. Exact canonical files can be adopted; disabling the task
 removes only unchanged owned files.
 
 The managed Vite config composes the shared Oxfmt and Oxlint presets, configures
-`vp staged`, and defines `vp run check` and `vp run typecheck`. The check task
-and CI run `vp fmt --check`, `vp lint`, `vp test`, then the Effect-patched
-compiler through `vp run typecheck`.
+`vp staged`, and defines separate `vp run check` and pure `vp run typecheck`
+tasks. The default `single-project` strategy runs one `tsc --noEmit` process and
+requires a root `tsconfig.json` without project references:
+
+```jsonc
+{
+  "setup": {
+    "effectTsgo": { "enabled": true },
+    "vitePlus": {
+      "quality": {
+        "enabled": true,
+        "typecheck": { "strategy": "single-project" },
+      },
+    },
+  },
+}
+```
+
+Workspaces can instead opt into Vite Task orchestration explicitly:
+
+```jsonc
+{
+  "setup": {
+    "effectTsgo": { "enabled": true },
+    "vitePlus": {
+      "quality": {
+        "enabled": true,
+        "typecheck": {
+          "strategy": "workspace",
+          "concurrency": 4,
+          "packages": ["apps/web", "packages/core"],
+        },
+      },
+    },
+  },
+}
+```
+
+Workspace mode requires `package.json#workspaces` and an explicit list of
+project-relative package directories. Each listed package must define a pure
+`typecheck` package script. Dev Kit generates Vite+ filters for exactly that
+scope with `--fail-if-no-match`; Vite Task uses ordinary workspace dependency
+order, forces script caching on, and bounds concurrency to the configured value
+(1–32). Dev Kit does not generate a project-reference mode: repositories that
+need `tsc -b` must keep the quality setup disabled and define a custom Vite task
+with deliberate `.tsbuildinfo` inputs and outputs.
+
+Generated CI performs exactly one `vp install` through
+`voidzero-dev/setup-vp`, using `--frozen-lockfile --ignore-scripts`, then runs
+`vp exec dev-kit apply --locked` before quality checks. This verifies the
+committed Dev Kit lock and explicitly converges the Effect TypeScript-Go patch
+without relying on a consumer lifecycle script or running an unlocked apply.
+Vite+ maps those install flags to the detected npm, pnpm, Yarn, or Bun project;
+the workflow does not pretend their native immutable/no-script flags are
+interchangeable.
+The template pins the exact commit for a supported `setup-vp` release because
+its `v1` tag is frozen; keep the annotated release commit current with Renovate
+or Dependabot. See the primary
+[`setup-vp` versioning guidance](https://github.com/voidzero-dev/setup-vp#versioning),
+[Vite+ install guide](https://viteplus.dev/guide/install), and
+[Vite Task run guide](https://viteplus.dev/guide/run) when maintaining these
+templates. The check task and CI then run `vp fmt --check`, `vp lint`,
+`vp test`, and `vp run typecheck`.
 
 ## Effect source checkout
 

package/dev-kit.example.jsonc

@@ -8,7 +8,10 @@
     "effectTsgo": { "enabled": true },
     "vitePlus": {
       "hooks": { "enabled": true },
-      "quality": { "enabled": true },
+      "quality": {
+        "enabled": true,
+        "typecheck": { "strategy": "single-project" },
+      },
     },
   },
   "targets": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danieljvdm/dev-kit",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "private": false,
   "description": "Declarative project development toolkit with portable agent skills.",
   "license": "MIT",
@@ -69,6 +69,7 @@
     "@stylistic/eslint-plugin": "5.10.0",
     "effect": "4.0.0-beta.102",
     "jsonc-parser": "3.3.1",
+    "semver": "7.8.5",
     "tsx": "4.22.4"
   },
   "devDependencies": {
@@ -76,6 +77,7 @@
     "@effect/tsgo": "0.24.3",
     "@effect/vitest": "4.0.0-beta.102",
     "@types/node": "25.9.1",
+    "@types/semver": "7.8.0",
     "oxfmt": "0.60.0",
     "oxlint": "1.75.0",
     "typescript": "7.0.2",

package/schema/dev-kit.schema.json

@@ -168,6 +168,37 @@
         "enabled": {
           "type": "boolean",
           "default": false
+        },
+        "typecheck": {
+          "$ref": "#/$defs/vitePlusQualityTypecheckSetup"
+        }
+      }
+    },
+    "vitePlusQualityTypecheckSetup": {
+      "description": "Select the managed typecheck topology. Single-project is the default; workspace mode runs explicitly scoped package scripts through Vite Task.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "strategy": {
+          "enum": ["single-project", "workspace"],
+          "default": "single-project"
+        },
+        "concurrency": {
+          "description": "Maximum concurrent workspace typecheck tasks.",
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 32,
+          "default": 4
+        },
+        "packages": {
+          "description": "Project-relative workspace package directories whose typecheck scripts should run.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true,
+          "default": []
         }
       }
     },

package/skills/dev-kit/SKILL.md

@@ -116,12 +116,27 @@ Effect TypeScript-Go, and native TypeScript dependencies, as well as
 `setup.effectTsgo.enabled`. It refuses custom destination files and conflicting
 `check` or `typecheck` package scripts. Exact canonical files can be adopted;
 later updates and cleanup occur only while the owned files remain unchanged.
+The installed Vite+ version must satisfy Dev Kit's package peer range; generated
+CI resolves the consumer's locked Vite+ rather than carrying a second version
+literal.
 
 The managed Vite config composes the shared formatter and linter presets,
-configures `vp staged`, and defines cached `check` and `typecheck` Vite tasks.
-The check task and GitHub Actions workflow run `vp fmt --check`, `vp lint`,
-`vp test`, and finally `vp run typecheck` so Effect diagnostics come from the
-patched native compiler.
+configures `vp staged`, and defines separate cached `check` and pure `typecheck`
+Vite tasks. The default `single-project` typecheck strategy runs
+`tsc --noEmit` and rejects root TypeScript project references. An explicit
+`workspace` strategy requires explicit package directories with consumer-owned
+`typecheck` scripts, then runs exactly that filter scope in workspace dependency
+order with caching enabled, unmatched-filter failure, and configurable bounded
+concurrency. Project-reference builds remain custom because they need
+repository-specific `.tsbuildinfo` inputs and outputs.
+
+The GitHub Actions workflow uses one frozen, script-suppressed install through
+an exact `setup-vp` release, then runs `vp exec dev-kit apply --locked`. This
+verifies the committed setup and converges the Effect TypeScript-Go patch before
+formatting, linting, tests, and typechecking. Vite+ maps the frozen and
+ignore-scripts flags to the detected package manager. Keep the exact setup
+action release commit current with Renovate or Dependabot; do not switch back
+to the frozen `v1` tag.
 
 ## Ownership and conflicts
 

package/src/index.ts

@@ -13,8 +13,12 @@ export {
   TargetConfigSchema,
   type VitePlusQualitySetup,
   VitePlusQualitySetupSchema,
+  type VitePlusQualityTypecheckSetup,
+  VitePlusQualityTypecheckSetupSchema,
   type VitePlusSetup,
   VitePlusSetupSchema,
+  type VitePlusTypecheckStrategy,
+  VitePlusTypecheckStrategySchema,
 } from "./manifest.ts";
 export {
   applyEffectSourcePlan,

package/src/manifest.ts

@@ -53,8 +53,19 @@ export const VitePlusHooksSetupSchema = Schema.Struct({
   enabled: Schema.optional(Schema.Boolean),
 });
 
+export const VitePlusTypecheckStrategySchema = Schema.Literals(["single-project", "workspace"]);
+export type VitePlusTypecheckStrategy = typeof VitePlusTypecheckStrategySchema.Type;
+
+export const VitePlusQualityTypecheckSetupSchema = Schema.Struct({
+  strategy: Schema.optional(VitePlusTypecheckStrategySchema),
+  concurrency: Schema.optional(Schema.Int),
+  packages: Schema.optional(Schema.Array(Schema.String)),
+});
+export type VitePlusQualityTypecheckSetup = typeof VitePlusQualityTypecheckSetupSchema.Type;
+
 export const VitePlusQualitySetupSchema = Schema.Struct({
   enabled: Schema.optional(Schema.Boolean),
+  typecheck: Schema.optional(VitePlusQualityTypecheckSetupSchema),
 });
 export type VitePlusQualitySetup = typeof VitePlusQualitySetupSchema.Type;
 
@@ -124,6 +135,11 @@ export type NormalizedManifest = {
       };
       readonly quality: {
         readonly enabled: boolean;
+        readonly typecheck: {
+          readonly strategy: VitePlusTypecheckStrategy;
+          readonly concurrency: number;
+          readonly packages: ReadonlyArray<string>;
+        };
       };
     };
   };
@@ -187,6 +203,11 @@ export const normalizeManifest = (manifest: DevKitManifest): NormalizedManifest
         },
         quality: {
           enabled: manifest.setup?.vitePlus?.quality?.enabled ?? false,
+          typecheck: {
+            strategy: manifest.setup?.vitePlus?.quality?.typecheck?.strategy ?? "single-project",
+            concurrency: manifest.setup?.vitePlus?.quality?.typecheck?.concurrency ?? 4,
+            packages: manifest.setup?.vitePlus?.quality?.typecheck?.packages ?? [],
+          },
         },
       },
     },

package/src/path-digest.ts

@@ -27,6 +27,7 @@ const textEncoder = new TextEncoder();
 // Git preserves only the executable distinction for regular files. Canonicalizing
 // the remaining bits keeps digests stable across checkout and copy umasks.
 const canonicalFileMode = (mode: number): number => ((mode & 0o111) === 0 ? 0o644 : 0o755);
+const rawFileMode = (mode: number): number => mode & 0o777;
 
 const frame = (value: string | Uint8Array): Uint8Array => {
   const bytes = typeof value === "string" ? textEncoder.encode(value) : value;
@@ -75,6 +76,7 @@ const digestFrames = Effect.fn("digestPathFrames")(function* (
 
 const digestFileSystemPath = Effect.fn("digestFileSystemPath")(function* (
   absolutePath: string,
+  fileMode: (mode: number) => number,
 ): Effect.fn.Return<
   ObservedPath,
   PlatformError.PlatformError | PathInspectionError,
@@ -107,7 +109,7 @@ const digestFileSystemPath = Effect.fn("digestFileSystemPath")(function* (
       kind: "file",
       digest: yield* digestFrames([
         "file-v1",
-        String(canonicalFileMode(info.mode)),
+        String(fileMode(info.mode)),
         yield* fs.readFile(absolutePath),
       ]),
     };
@@ -119,7 +121,7 @@ const digestFileSystemPath = Effect.fn("digestFileSystemPath")(function* (
 
     for (const entry of entries) {
       const childPath = path.join(absolutePath, entry);
-      const child = yield* digestFileSystemPath(childPath);
+      const child = yield* digestFileSystemPath(childPath, fileMode);
 
       if (child.kind === "missing") {
         return yield* new PathInspectionError({
@@ -142,7 +144,19 @@ const digestFileSystemPath = Effect.fn("digestFileSystemPath")(function* (
 });
 
 export const observePath = Effect.fn("observeManagedPath")(function* (absolutePath: string) {
-  return yield* digestFileSystemPath(absolutePath).pipe(
+  return yield* digestFileSystemPath(absolutePath, canonicalFileMode).pipe(
+    Effect.mapError((cause) =>
+      cause instanceof PathInspectionError
+        ? cause
+        : new PathInspectionError({ path: absolutePath, operation: "inspect", cause }),
+    ),
+  );
+});
+
+export const observePathWithRawModes = Effect.fn("observeManagedPathWithRawModes")(function* (
+  absolutePath: string,
+) {
+  return yield* digestFileSystemPath(absolutePath, rawFileMode).pipe(
     Effect.mapError((cause) =>
       cause instanceof PathInspectionError
         ? cause

package/src/project-package.ts

@@ -13,6 +13,7 @@ const ProjectPackageSchema = Schema.fromJsonString(
     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)),
+    workspaces: Schema.optional(Schema.Unknown),
   }),
 );
 

package/src/sync.ts

@@ -23,6 +23,7 @@ import {
   digestSymlinkTarget,
   digestText,
   observePath,
+  observePathWithRawModes,
   type ObservedPath,
 } from "./path-digest.ts";
 import { readDirectDependencyNames } from "./project-package.ts";
@@ -47,6 +48,8 @@ import {
   type VitePlusHooksPlan,
 } from "./vite-plus-hooks.ts";
 import {
+  renderVitePlusConfigTemplate,
+  renderVitePlusWorkflowTemplate,
   validateVitePlusQualitySupport,
   VITE_PLUS_CONFIG_PATH,
   VITE_PLUS_CONFIG_TEMPLATE,
@@ -430,6 +433,27 @@ const outputIdentity = (output: ManagedOutput) =>
       : { sourcePath: output.sourcePath }),
   });
 
+const outputOwnershipIdentity = (output: ManagedOutput) =>
+  JSON.stringify({
+    resourceId: output.resourceId,
+    path: output.path,
+    mode: output.mode,
+    kind: output.kind,
+    ...("skill" in output
+      ? { skill: output.skill, target: output.target }
+      : { sourcePath: output.sourcePath }),
+  });
+
+const usesRawFileModeDigests = (toolVersion: string): boolean => {
+  const match = /^(\d+)\.(\d+)\./.exec(toolVersion);
+
+  if (match === null) return false;
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+
+  return major === 0 && minor <= 6;
+};
+
 const validateInventory = Effect.fn("validateManagedInventory")(function* (
   projectDir: string,
   outputs: ReadonlyArray<ManagedOutput | OwnershipReceipt>,
@@ -624,7 +648,16 @@ const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
       },
     ]) {
       const managed = yield* resolveManagedPath(projectDir, generated.path);
-      const content = yield* readGeneratedFileTemplate(packageRoot, generated.sourcePath);
+      const template = yield* readGeneratedFileTemplate(packageRoot, generated.sourcePath);
+      const content =
+        generated.resourceId === "setup:vite-plus-config"
+          ? renderVitePlusConfigTemplate(template, setup.vitePlus.quality.typecheck)
+          : renderVitePlusWorkflowTemplate(
+              template,
+              projectDir === packageRoot
+                ? "./bin/dev-kit.mjs apply --locked"
+                : "vp exec dev-kit apply --locked",
+            );
 
       outputs.push({
         resourceId: generated.resourceId,
@@ -743,12 +776,31 @@ const planDesiredOutputs = Effect.fn("planDesiredSkillOutputs")(function* (
     const receipt = receiptsById.get(output.resourceId);
     const sameReceipt = receipt?.path === output.path ? receipt : undefined;
     const locked = lockById.get(output.resourceId);
-    const adoptable = locked !== undefined && outputIdentity(locked) === outputIdentity(output);
+    const matchingLockedOutput =
+      locked !== undefined &&
+      outputOwnershipIdentity(locked) === outputOwnershipIdentity(output) &&
+      observed.kind === locked.kind
+        ? locked
+        : undefined;
+    const rawModeObservation =
+      matchingLockedOutput !== undefined &&
+      observed.kind !== "missing" &&
+      observed.digest !== matchingLockedOutput.digest &&
+      currentLock !== undefined &&
+      usesRawFileModeDigests(currentLock.toolVersion)
+        ? yield* observePathWithRawModes(output.destination)
+        : undefined;
+    const lockedOwnsObserved =
+      matchingLockedOutput !== undefined &&
+      observed.kind !== "missing" &&
+      (observed.digest === matchingLockedOutput.digest ||
+        (rawModeObservation?.kind === matchingLockedOutput.kind &&
+          rawModeObservation.digest === matchingLockedOutput.digest));
 
     if (observed.kind === "missing") {
       actions.push({ action: "create", desired: output, observed });
     } else if (observed.kind === output.kind && observed.digest === output.digest) {
-      if (sameReceipt || adoptable || ("adoptIfExact" in output && output.adoptIfExact)) {
+      if (sameReceipt || lockedOwnsObserved || ("adoptIfExact" in output && output.adoptIfExact)) {
         actions.push({ action: "unchanged", desired: output, observed, adopted: !sameReceipt });
       } else {
         actions.push({
@@ -758,9 +810,10 @@ const planDesiredOutputs = Effect.fn("planDesiredSkillOutputs")(function* (
         });
       }
     } else if (
-      sameReceipt &&
-      observed.kind === sameReceipt.kind &&
-      observed.digest === sameReceipt.digest
+      (sameReceipt !== undefined &&
+        observed.kind === sameReceipt.kind &&
+        observed.digest === sameReceipt.digest) ||
+      lockedOwnsObserved
     ) {
       actions.push({ action: "update", desired: output, observed });
     } else {
@@ -876,6 +929,7 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
       projectDir,
       packageRoot,
       manifest.setup.effectTsgo.typescriptPackage,
+      manifest.setup.vitePlus.quality.typecheck,
     );
   }
   const effectSource = manifest.setup.effectSource.enabled

package/src/tool-metadata.ts

@@ -1,3 +1,5 @@
 import packageMetadata from "../package.json" with { type: "json" };
 
 export const DEV_KIT_VERSION = packageMetadata.version;
+export const VITE_PLUS_TESTED_VERSION = packageMetadata.devDependencies["vite-plus"];
+export const VITE_PLUS_SUPPORTED_RANGE = packageMetadata.peerDependencies["vite-plus"];

package/src/vite-plus-dependency.ts

@@ -0,0 +1,70 @@
+import { Effect, FileSystem, Path, Schema } from "effect";
+import semver from "semver";
+
+import { readDirectDependencyNames } from "./project-package.ts";
+import { VITE_PLUS_SUPPORTED_RANGE } from "./tool-metadata.ts";
+
+const InstalledVitePlusPackageSchema = Schema.fromJsonString(
+  Schema.Struct({ version: Schema.String }),
+);
+
+export class VitePlusDependencyError extends Schema.TaggedErrorClass<VitePlusDependencyError>()(
+  "VitePlusDependencyError",
+  { message: Schema.String },
+) {}
+
+export type InstalledVitePlus = {
+  readonly version: string;
+  readonly vpBin: string;
+};
+
+export const validateInstalledVitePlus = Effect.fn("validateInstalledVitePlus")(function* (
+  projectDir: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const dependencies = yield* readDirectDependencyNames(projectDir);
+
+  if (!dependencies.includes("vite-plus")) {
+    return yield* new VitePlusDependencyError({
+      message: "vite-plus must be a direct project dependency",
+    });
+  }
+  const packagePath = path.join(projectDir, "node_modules", "vite-plus", "package.json");
+
+  if (!(yield* fs.exists(packagePath))) {
+    return yield* new VitePlusDependencyError({
+      message:
+        "vite-plus must be installed before enabling this setup: node_modules/vite-plus/package.json is missing",
+    });
+  }
+  const installed = yield* fs.readFileString(packagePath).pipe(
+    Effect.flatMap(Schema.decodeUnknownEffect(InstalledVitePlusPackageSchema)),
+    Effect.mapError(
+      () =>
+        new VitePlusDependencyError({
+          message: "installed vite-plus package metadata has no valid version",
+        }),
+    ),
+  );
+
+  if (!semver.valid(installed.version)) {
+    return yield* new VitePlusDependencyError({
+      message: `installed vite-plus package metadata has invalid version: ${installed.version}`,
+    });
+  }
+  if (!semver.satisfies(installed.version, VITE_PLUS_SUPPORTED_RANGE)) {
+    return yield* new VitePlusDependencyError({
+      message: `installed vite-plus ${installed.version} is incompatible with @danieljvdm/dev-kit; supported range: ${VITE_PLUS_SUPPORTED_RANGE}`,
+    });
+  }
+  const vpBin = path.join(projectDir, "node_modules", ".bin", "vp");
+
+  if (!(yield* fs.exists(vpBin))) {
+    return yield* new VitePlusDependencyError({
+      message: "vite-plus is installed but node_modules/.bin/vp is missing",
+    });
+  }
+
+  return { version: installed.version, vpBin } satisfies InstalledVitePlus;
+});

package/src/vite-plus-hooks.ts

@@ -1,7 +1,7 @@
 import { Config, Effect, FileSystem, Path, Schema, Stream } from "effect";
 import { ChildProcess } from "effect/unstable/process";
 
-import { readDirectDependencyNames } from "./project-package.ts";
+import { validateInstalledVitePlus } from "./vite-plus-dependency.ts";
 
 export const VITE_PLUS_HOOKS_DIR = ".vite-hooks";
 export const VITE_PLUS_HOOKS_PATH = `${VITE_PLUS_HOOKS_DIR}/_`;
@@ -121,23 +121,14 @@ const inspectVitePlusHooks = Effect.fn("inspectVitePlusHooks")(function* (projec
 });
 
 export const planVitePlusHooks = Effect.fn("planVitePlusHooks")(function* (projectDir: string) {
-  const fs = yield* FileSystem.FileSystem;
-  const path = yield* Path.Path;
-  const dependencies = yield* readDirectDependencyNames(projectDir);
-
-  if (!dependencies.includes("vite-plus")) {
-    return yield* new VitePlusHooksDependencyError({
-      message: "vite-plus must be a direct project dependency before enabling setup.vitePlus.hooks",
-    });
-  }
-  const vpBin = path.join(projectDir, "node_modules", ".bin", "vp");
-
-  if (!(yield* fs.exists(vpBin))) {
-    return yield* new VitePlusHooksDependencyError({
-      message:
-        "vite-plus must be installed before enabling setup.vitePlus.hooks: node_modules/.bin/vp is missing",
-    });
-  }
+  const { vpBin } = yield* validateInstalledVitePlus(projectDir).pipe(
+    Effect.mapError(
+      (error) =>
+        new VitePlusHooksDependencyError({
+          message: `${error.message} before enabling setup.vitePlus.hooks`,
+        }),
+    ),
+  );
   const viteGitHooks = yield* Config.string("VITE_GIT_HOOKS").pipe(Config.withDefault(""));
   const husky = yield* Config.string("HUSKY").pipe(Config.withDefault(""));
   const action =

package/src/vite-plus-quality.ts

@@ -1,6 +1,9 @@
 import { Effect, FileSystem, Path, Schema } from "effect";
+import { parse as parseJsonc, type ParseError } from "jsonc-parser";
 
+import type { VitePlusTypecheckStrategy } from "./manifest.ts";
 import { readDirectDependencyNames, readProjectPackage } from "./project-package.ts";
+import { validateInstalledVitePlus } from "./vite-plus-dependency.ts";
 
 export const VITE_PLUS_CONFIG_PATH = "vite.config.ts";
 export const VITE_PLUS_CONFIG_TEMPLATE = "templates/vite-plus/vite.config.ts";
@@ -12,13 +15,75 @@ export class VitePlusQualitySupportError extends Schema.TaggedErrorClass<VitePlu
   { message: Schema.String },
 ) {}
 
+export type VitePlusQualityTypecheck = {
+  readonly strategy: VitePlusTypecheckStrategy;
+  readonly concurrency: number;
+  readonly packages: ReadonlyArray<string>;
+};
+
+const SINGLE_PROJECT_TYPECHECK_TASK = '      typecheck: "tsc --noEmit",';
+const LOCKED_DEV_KIT_COMMAND = "vp exec dev-kit apply --locked";
+
+const replaceUniqueTemplateMarker = (
+  template: string,
+  marker: string,
+  replacement: string,
+): string => {
+  const parts = template.split(marker);
+
+  if (parts.length !== 2) {
+    throw new Error(`expected exactly one generated template marker: ${marker}`);
+  }
+
+  return `${parts[0]}${replacement}${parts[1]}`;
+};
+
+const shellQuote = (value: string): string => `'${value.replaceAll("'", `'"'"'`)}'`;
+
+export const renderVitePlusConfigTemplate = (
+  template: string,
+  typecheck: VitePlusQualityTypecheck,
+): string => {
+  if (typecheck.strategy === "single-project") return template;
+  const filters = typecheck.packages
+    .map((packageDir) => `--filter ${shellQuote(`./${packageDir}`)}`)
+    .join(" ");
+  const command = `vp run --cache --concurrency-limit ${typecheck.concurrency} ${filters} --fail-if-no-match typecheck`;
+
+  return replaceUniqueTemplateMarker(
+    template,
+    SINGLE_PROJECT_TYPECHECK_TASK,
+    `      typecheck: {
+        command: ${JSON.stringify(command)},
+        cache: false,
+      },`,
+  );
+};
+
+export const renderVitePlusWorkflowTemplate = (
+  template: string,
+  devKitCommand = LOCKED_DEV_KIT_COMMAND,
+): string =>
+  devKitCommand === LOCKED_DEV_KIT_COMMAND
+    ? template
+    : replaceUniqueTemplateMarker(template, LOCKED_DEV_KIT_COMMAND, devKitCommand);
+
 export const validateVitePlusQualitySupport = Effect.fn("validateVitePlusQualitySupport")(
-  function* (projectDir: string, packageRoot: string, typescriptPackage: string) {
+  function* (
+    projectDir: string,
+    packageRoot: string,
+    typescriptPackage: string,
+    typecheck: VitePlusQualityTypecheck,
+  ) {
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
     const packageJson = yield* readProjectPackage(projectDir);
     const dependencies = yield* readDirectDependencyNames(projectDir);
-    const required = new Set(["vite-plus", "effect", "@effect/tsgo", typescriptPackage]);
+    const required = new Set(["effect", "@effect/tsgo", typescriptPackage]);
+
+    yield* validateInstalledVitePlus(projectDir).pipe(
+      Effect.mapError((error) => new VitePlusQualitySupportError({ message: error.message })),
+    );
 
     if (projectDir !== packageRoot) required.add("@danieljvdm/dev-kit");
     const missing = [...required].filter((dependency) => !dependencies.includes(dependency));
@@ -37,13 +102,104 @@ export const validateVitePlusQualitySupport = Effect.fn("validateVitePlusQuality
         message: `setup.vitePlus.quality defines Vite tasks that conflict with package scripts: ${conflictingScripts.join(", ")}`,
       });
     }
-    const vpBin = path.join(projectDir, "node_modules", ".bin", "vp");
-
-    if (!(yield* fs.exists(vpBin))) {
+    if (typecheck.concurrency < 1 || typecheck.concurrency > 32) {
+      return yield* new VitePlusQualitySupportError({
+        message: "setup.vitePlus.quality typecheck concurrency must be between 1 and 32",
+      });
+    }
+    if (typecheck.strategy === "single-project" && typecheck.packages.length > 0) {
       return yield* new VitePlusQualitySupportError({
         message:
-          "vite-plus must be installed before enabling setup.vitePlus.quality: node_modules/.bin/vp is missing",
+          "setup.vitePlus.quality single-project typechecking does not accept workspace packages",
+      });
+    }
+    const workspacePatterns = Array.isArray(packageJson.workspaces)
+      ? packageJson.workspaces
+      : typeof packageJson.workspaces === "object" && packageJson.workspaces !== null
+        ? (packageJson.workspaces as { readonly packages?: unknown }).packages
+        : undefined;
+
+    if (
+      typecheck.strategy === "workspace" &&
+      (!Array.isArray(workspacePatterns) ||
+        workspacePatterns.length === 0 ||
+        !workspacePatterns.every((pattern) => typeof pattern === "string"))
+    ) {
+      return yield* new VitePlusQualitySupportError({
+        message: "setup.vitePlus.quality workspace typechecking requires package.json workspaces",
+      });
+    }
+    if (typecheck.strategy === "workspace") {
+      if (typecheck.packages.length === 0) {
+        return yield* new VitePlusQualitySupportError({
+          message:
+            "setup.vitePlus.quality workspace typechecking requires explicit package directories",
+        });
+      }
+      const uniquePackages = new Set(typecheck.packages);
+
+      if (uniquePackages.size !== typecheck.packages.length) {
+        return yield* new VitePlusQualitySupportError({
+          message: "setup.vitePlus.quality workspace typecheck packages must be unique",
+        });
+      }
+      for (const packageDir of typecheck.packages) {
+        const absolute = path.resolve(projectDir, packageDir);
+        const relative = path.relative(projectDir, absolute);
+
+        if (
+          packageDir.length === 0 ||
+          path.isAbsolute(packageDir) ||
+          relative.length === 0 ||
+          relative === ".." ||
+          relative.startsWith(`..${path.sep}`)
+        ) {
+          return yield* new VitePlusQualitySupportError({
+            message: `setup.vitePlus.quality workspace package must be a project-relative subdirectory: ${packageDir}`,
+          });
+        }
+        const workspacePackage = yield* readProjectPackage(absolute).pipe(
+          Effect.mapError(
+            () =>
+              new VitePlusQualitySupportError({
+                message: `setup.vitePlus.quality workspace package is missing a valid package.json: ${packageDir}`,
+              }),
+          ),
+        );
+
+        if (workspacePackage.scripts?.typecheck === undefined) {
+          return yield* new VitePlusQualitySupportError({
+            message: `setup.vitePlus.quality workspace package requires a typecheck script: ${packageDir}`,
+          });
+        }
+      }
+    }
+    if (typecheck.strategy === "single-project") {
+      const tsconfigPath = path.join(projectDir, "tsconfig.json");
+
+      if (!(yield* fs.exists(tsconfigPath))) {
+        return yield* new VitePlusQualitySupportError({
+          message: "setup.vitePlus.quality single-project typechecking requires tsconfig.json",
+        });
+      }
+      const errors: Array<ParseError> = [];
+      const tsconfig = parseJsonc(yield* fs.readFileString(tsconfigPath), errors, {
+        allowTrailingComma: true,
       });
+
+      if (errors.length > 0 || typeof tsconfig !== "object" || tsconfig === null) {
+        return yield* new VitePlusQualitySupportError({
+          message: "setup.vitePlus.quality requires a valid root tsconfig.json",
+        });
+      }
+      const references = (tsconfig as { readonly references?: unknown }).references;
+
+      if (Array.isArray(references) && references.length > 0) {
+        return yield* new VitePlusQualitySupportError({
+          message:
+            "setup.vitePlus.quality single-project typechecking does not support tsconfig project references; select the workspace strategy or use a custom Vite config",
+        });
+      }
     }
   },
 );

package/templates/vite-plus/github-actions-check.yml

@@ -22,14 +22,19 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Set up Vite+
-        uses: voidzero-dev/setup-vp@v1
+      # setup-vp's v1 tag is frozen. Keep this v1.16.1 commit current with
+      # Renovate or Dependabot so fixes arrive through reviewed pull requests.
+      - name: Set up Vite+ and install dependencies
+        uses: voidzero-dev/setup-vp@143f5f385f39b1b753ffed1a01ad443811855c8b # v1.16.1
         with:
+          # Vite+ version intentionally resolves from the consumer manifest/lock.
           node-version: "24"
           cache: true
+          run-install: |
+            args: ["--frozen-lockfile", "--ignore-scripts"]
 
-      - name: Install dependencies
-        run: vp install
+      - name: Verify locked Dev Kit setup
+        run: vp exec dev-kit apply --locked
 
       - name: Check formatting
         run: vp fmt --check