@danieljvdm/dev-kit 0.14.0 → 0.16.0

package/src/scaffold.ts

@@ -0,0 +1,79 @@
+import { Effect, FileSystem, Path, Schema } from "effect";
+
+import { observeSymbolicLink } from "./node-symbolic-link.ts";
+
+export class ScaffoldTemplateError extends Schema.TaggedError<ScaffoldTemplateError>()(
+  "ScaffoldTemplateError",
+  { message: Schema.String },
+) {}
+
+export type ScaffoldPlan = {
+  readonly action: "scaffold" | "unchanged";
+  readonly path: string;
+  readonly destination: string;
+  readonly content?: string;
+};
+
+export 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]}`;
+};
+
+export const readScaffoldTemplate = Effect.fn("readScaffoldTemplate")(function* (
+  packageRoot: string,
+  templatePath: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const absolute = path.join(packageRoot, templatePath);
+
+  if (!(yield* fs.exists(absolute))) {
+    return yield* ScaffoldTemplateError.make({
+      message: `dev-kit scaffold template is missing: ${templatePath}`,
+    });
+  }
+
+  return yield* fs.readFileString(absolute);
+});
+
+// Scaffolds are created once and repository-owned afterwards: an existing
+// destination is never read, compared, updated, or removed, and `content` is
+// only computed (and validated) when the file is actually being created.
+export const planScaffold = Effect.fn("planScaffold")(function* <E, R>(options: {
+  readonly projectDir: string;
+  readonly path: string;
+  readonly content: Effect.Effect<string, E, R>;
+}) {
+  const path = yield* Path.Path;
+  const destination = path.join(options.projectDir, ...options.path.split("/"));
+  const observed = yield* observeSymbolicLink(destination);
+
+  if (observed.kind !== "missing") {
+    return { action: "unchanged", path: options.path, destination } satisfies ScaffoldPlan;
+  }
+
+  return {
+    action: "scaffold",
+    path: options.path,
+    destination,
+    content: yield* options.content,
+  } satisfies ScaffoldPlan;
+});
+
+export const applyScaffoldPlan = Effect.fn("applyScaffoldPlan")(function* (plan: ScaffoldPlan) {
+  if (plan.action !== "scaffold" || plan.content === undefined) return;
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+
+  yield* fs.makeDirectory(path.dirname(plan.destination), { recursive: true });
+  yield* fs.writeFileString(plan.destination, plan.content);
+});

package/src/sync.ts

@@ -15,6 +15,7 @@ import {
   planEffectTsgoPatch,
   type EffectTsgoPatchPlan,
 } from "./effect-tsgo.ts";
+import { maybePruneGlobalCache } from "./global-cache.ts";
 import { DevKitManifestSchema, normalizeManifest } from "./manifest.ts";
 import { observeSymbolicLink } from "./node-symbolic-link.ts";
 import { resolvePackageSkillSelector } from "./package-skill-source.ts";
@@ -23,10 +24,16 @@ import {
   digestSymlinkTarget,
   digestText,
   observePath,
-  observePathWithRawModes,
   type ObservedPath,
 } from "./path-digest.ts";
-import { readDirectDependencyNames, readProjectPackage } from "./project-package.ts";
+import {
+  detectPackageManager,
+  PACKAGE_MANAGER_COMMANDS,
+  readDirectDependencyNames,
+  readWorkspaceDependencyNames,
+  readProjectPackage,
+  type PackageManagerName,
+} from "./project-package.ts";
 import { acquireProjectProcessLock, PROJECT_PROCESS_LOCK_PATH } from "./project-process-lock.ts";
 import {
   AppliedStateSchema,
@@ -38,11 +45,11 @@ import {
   type DevKitLock,
   type ManagedAgentInstructionsOutput,
   type ManagedClaudeInstructionsOutput,
-  type ManagedGeneratedFileOutput,
   type ManagedOutput,
   type ManagedSkillOutput,
   type OwnershipReceipt,
 } from "./project-state.ts";
+import { applyScaffoldPlan, type ScaffoldPlan } from "./scaffold.ts";
 import { parseSkillSelector } from "./skill-selector.ts";
 import { DEV_KIT_VERSION } from "./tool-metadata.ts";
 import {
@@ -50,12 +57,8 @@ import {
   planVitePlusHooks,
   type VitePlusHooksPlan,
 } from "./vite-plus-hooks.ts";
-import {
-  renderVitePlusWorkflowTemplate,
-  validateVitePlusQualitySupport,
-  VITE_PLUS_GITHUB_ACTIONS_PATH,
-  VITE_PLUS_GITHUB_ACTIONS_TEMPLATE,
-} from "./vite-plus-quality.ts";
+import { planVitePlusWorkflow } from "./vite-plus-workflow.ts";
+import { planWorktrunkConfig } from "./worktrunk-config.ts";
 
 export type SyncOptions = {
   readonly manifestPath?: string;
@@ -98,17 +101,10 @@ type DesiredClaudeInstructionsOutput = ManagedClaudeInstructionsOutput & {
   readonly linkTarget: string;
 };
 
-type DesiredGeneratedFileOutput = ManagedGeneratedFileOutput & {
-  readonly adoptIfExact: true;
-  readonly content: string;
-  readonly destination: string;
-};
-
 type DesiredOutput =
   | DesiredSkillOutput
   | DesiredAgentInstructionsOutput
-  | DesiredClaudeInstructionsOutput
-  | DesiredGeneratedFileOutput;
+  | DesiredClaudeInstructionsOutput;
 
 type SkillPlanAction =
   | {
@@ -144,6 +140,8 @@ export type SkillPlan = {
   readonly effectSource?: EffectSourcePlan;
   readonly effectTsgo?: EffectTsgoPatchPlan;
   readonly vitePlusHooks?: VitePlusHooksPlan;
+  readonly vitePlusWorkflow?: ScaffoldPlan;
+  readonly worktrunkConfig?: ScaffoldPlan;
   readonly nextLock: DevKitLock;
   readonly nextState: AppliedState;
   readonly metadataChanged: boolean;
@@ -270,7 +268,13 @@ const encodePlanSnapshotJson = Schema.encodeSync(Schema.fromJsonString(Schema.Un
 const encodeAppliedStatePrettyJson = Schema.encodeSync(fromJsonString(AppliedStateSchema, 2));
 
 const SKILL_FAMILIES: SkillCatalog = {
-  effect: ["effect-ts", "effect-architecture-audit", "build-effect-apis", "build-effect-clis"],
+  effect: [
+    "effect-ts",
+    "effect-architecture-audit",
+    "build-effect-apis",
+    "effect-atom-state",
+    "build-effect-clis",
+  ],
 };
 
 export const DEFAULT_MANIFEST = "dev-kit.jsonc";
@@ -436,57 +440,6 @@ const renderVitePlusCommandPolicy = (
   ].join("\n");
 };
 
-const PACKAGE_MANAGER_COMMANDS = {
-  bun: { install: "bun install", label: "Bun" },
-  npm: { install: "npm install", label: "npm" },
-  pnpm: { install: "pnpm install", label: "pnpm" },
-  yarn: { install: "yarn install", label: "Yarn" },
-} as const;
-
-type PackageManagerName = keyof typeof PACKAGE_MANAGER_COMMANDS;
-
-const packageManagerName = (declaration: string | undefined): PackageManagerName | undefined => {
-  const name = declaration?.split("@", 1)[0];
-
-  return name !== undefined && name in PACKAGE_MANAGER_COMMANDS
-    ? (name as PackageManagerName)
-    : undefined;
-};
-
-const detectPackageManager = Effect.fn("detectPackageManager")(function* (
-  projectDir: string,
-  declaration: string | undefined,
-) {
-  const declared = packageManagerName(declaration);
-
-  if (declared !== undefined || declaration !== undefined) return declared;
-  const fs = yield* FileSystem.FileSystem;
-  const path = yield* Path.Path;
-  const lockfiles: ReadonlyArray<readonly [PackageManagerName, ReadonlyArray<string>]> = [
-    ["bun", ["bun.lock", "bun.lockb"]],
-    ["npm", ["package-lock.json", "npm-shrinkwrap.json"]],
-    ["pnpm", ["pnpm-lock.yaml"]],
-    ["yarn", ["yarn.lock"]],
-  ];
-  const detected: Array<PackageManagerName> = [];
-
-  for (const [manager, files] of lockfiles) {
-    let found = false;
-
-    for (const file of files) {
-      if (yield* fs.exists(path.join(projectDir, file))) {
-        found = true;
-        break;
-      }
-    }
-    if (found) {
-      detected.push(manager);
-    }
-  }
-
-  return detected.length === 1 ? detected[0] : undefined;
-});
-
 const renderPackageScriptCommandPolicy = (
   manager: PackageManagerName | undefined,
   scripts: Readonly<Record<string, string>>,
@@ -746,16 +699,6 @@ const outputOwnershipIdentity = (output: ManagedOutput) =>
         },
   );
 
-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>,
@@ -870,7 +813,7 @@ const renderAgentInstructions = Effect.fn("renderAgentInstructions")(function* (
           );
   const directDependencyNames = yield* readDirectDependencyNames(projectDir);
   const usesVitePlus = directDependencyNames.includes("vite-plus");
-  const effectInstructions =
+  const effectGuideInstructions =
     directDependencyNames.includes("effect") &&
     (yield* observePath(path.join(projectDir, "node_modules", "effect", "AGENTS.md"))).kind ===
       "file"
@@ -886,6 +829,20 @@ guide doesn't cover, search through the source code in \`node_modules/effect/src
 
 `
       : "";
+  const atomBoundaryInstructions = (yield* readWorkspaceDependencyNames(projectDir)).includes(
+    "@effect/atom-react",
+  )
+    ? `# Effect Atom client boundary
+
+This repository consumes APIs through Effect Atom clients (\`@effect/atom-react\`).
+Keep business logic in Effect: compose multi-step client workflows as atoms,
+declare cross-query invalidation as reactivity keys on mutations, and keep
+promise-mode dispatches at the React boundary logic-free — no \`.then\` chains
+in components or routes.
+
+`
+    : "";
+  const effectInstructions = `${effectGuideInstructions}${atomBoundaryInstructions}`;
   const projectPackage = yield* readProjectPackage(projectDir).pipe(
     Effect.catchTag("ProjectPackageError", (error) =>
       error.message.startsWith("package.json not found:") ? Effect.void : Effect.fail(error),
@@ -904,23 +861,6 @@ guide doesn't cover, search through the source code in \`node_modules/effect/src
   return `${devKitInstructions}\n`;
 });
 
-const readGeneratedFileTemplate = Effect.fn("readGeneratedFileTemplate")(function* (
-  packageRoot: string,
-  sourcePath: string,
-) {
-  const fs = yield* FileSystem.FileSystem;
-  const path = yield* Path.Path;
-  const templatePath = path.join(packageRoot, sourcePath);
-
-  if ((yield* observePath(templatePath)).kind !== "file") {
-    return yield* InvalidProjectStateError.make({
-      message: `dev-kit generated file template is not a regular file: ${sourcePath}`,
-    });
-  }
-
-  return yield* fs.readFileString(templatePath);
-});
-
 const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
   packageRoot: string,
   projectDir: string,
@@ -938,9 +878,7 @@ const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
       packageRoot,
       projectDir,
       sourceBySkill,
-      setup.vitePlus.quality.workflow.enabled &&
-        setup.vitePlus.quality.workflow.typecheck.length === 1 &&
-        setup.vitePlus.quality.workflow.typecheck[0] === "vp run typecheck",
+      setup.vitePlus.workflow.enabled,
       targets,
     );
 
@@ -980,32 +918,6 @@ const buildDesiredOutputs = Effect.fn("buildDesiredSkillOutputs")(function* (
       linkTarget,
     });
   }
-  if (setup.vitePlus.quality.workflow.enabled) {
-    const managed = yield* resolveManagedPath(projectDir, VITE_PLUS_GITHUB_ACTIONS_PATH);
-    const template = yield* readGeneratedFileTemplate(
-      packageRoot,
-      VITE_PLUS_GITHUB_ACTIONS_TEMPLATE,
-    );
-    const content = renderVitePlusWorkflowTemplate(template, {
-      devKitCommand:
-        projectDir === packageRoot
-          ? "./bin/dev-kit.mjs apply --locked"
-          : "bun ./node_modules/@danieljvdm/dev-kit/bin/dev-kit.mjs apply --locked",
-      workflow: setup.vitePlus.quality.workflow,
-    });
-
-    outputs.push({
-      resourceId: "setup:vite-plus-github-actions",
-      path: managed.relative,
-      sourcePath: VITE_PLUS_GITHUB_ACTIONS_TEMPLATE,
-      mode: "copy",
-      kind: "file",
-      digest: yield* digestFileContent(content),
-      destination: managed.absolute,
-      content,
-      adoptIfExact: true,
-    });
-  }
   const agentsTarget = targets.agents;
   const duplicateOutput = skills.find(
     (skill, index) => skills.findIndex((candidate) => candidate.name === skill.name) !== index,
@@ -1116,20 +1028,10 @@ const planDesiredOutputs = Effect.fn("planDesiredSkillOutputs")(function* (
       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));
+      observed.digest === matchingLockedOutput.digest;
 
     if (output.resourceId === "setup:agent-instructions" && "content" in output) {
       if (observed.kind === "missing") {
@@ -1217,7 +1119,7 @@ const planDesiredOutputs = Effect.fn("planDesiredSkillOutputs")(function* (
     if (observed.kind === "missing") {
       actions.push({ action: "create", desired: output, observed });
     } else if (observed.kind === output.kind && observed.digest === output.digest) {
-      if (sameReceipt || lockedOwnsObserved || ("adoptIfExact" in output && output.adoptIfExact)) {
+      if (sameReceipt || lockedOwnsObserved) {
         actions.push({ action: "unchanged", desired: output, observed, adopted: !sameReceipt });
       } else {
         actions.push({
@@ -1375,28 +1277,6 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
   const packageRoot = yield* resolvePackageRoot();
   const manifest = normalizeManifest(yield* readManifest(manifestManaged.absolute));
 
-  const vitePlusQuality = manifest.setup.vitePlus.quality;
-  const vitePlusQualityEnabled = vitePlusQuality.workflow.enabled;
-
-  if (vitePlusQualityEnabled) {
-    if (!manifest.setup.effectTsgo.enabled) {
-      return yield* InvalidProjectStateError.make({
-        message:
-          "setup.vitePlus.quality requires setup.effectTsgo.enabled so managed quality setup converges the Effect-patched compiler",
-      });
-    }
-    yield* validateVitePlusQualitySupport(
-      projectDir,
-      packageRoot,
-      manifest.setup.effectTsgo.typescriptPackage,
-      {
-        workflow: {
-          beforeChecks: vitePlusQuality.workflow.beforeChecks,
-          typecheck: vitePlusQuality.workflow.typecheck,
-        },
-      },
-    );
-  }
   const effectSource = manifest.setup.effectSource.enabled
     ? yield* planEffectSource({
         packageName: manifest.setup.effectSource.packageName,
@@ -1415,6 +1295,17 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
   const vitePlusHooks = manifest.setup.vitePlus.hooks.enabled
     ? yield* planVitePlusHooks(projectDir)
     : undefined;
+  const vitePlusWorkflow = manifest.setup.vitePlus.workflow.enabled
+    ? yield* planVitePlusWorkflow({
+        packageRoot,
+        projectDir,
+        effectTsgoEnabled: manifest.setup.effectTsgo.enabled,
+        typescriptPackage: manifest.setup.effectTsgo.typescriptPackage,
+      })
+    : undefined;
+  const worktrunkConfig = manifest.setup.worktrunk.config.enabled
+    ? yield* planWorktrunkConfig(packageRoot, projectDir)
+    : undefined;
   const catalog = yield* loadSkillCatalog(packageRoot, projectDir);
   const availableSkills = catalog.skills.map((skill) => skill.selector);
   const skillFamilies = { ...SKILL_FAMILIES, ...catalog.families };
@@ -1521,16 +1412,6 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
           digest: output.digest,
         };
       }
-      if (output.resourceId === "setup:claude-instructions") {
-        return {
-          resourceId: output.resourceId,
-          path: output.path,
-          sourcePath: output.sourcePath,
-          mode: output.mode,
-          kind: output.kind,
-          digest: output.digest,
-        };
-      }
 
       return {
         resourceId: output.resourceId,
@@ -1553,8 +1434,22 @@ 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);
+  const rawLock = yield* readOptionalStructuredFile(lockManaged.absolute, DevKitLockSchema);
+  const rawState = yield* readOptionalStructuredFile(stateManaged.absolute, AppliedStateSchema);
+  // Migration: dev-kit ≤0.14 owned the check workflow as a managed output. It
+  // is a scaffold now, so stale lock entries and receipts are dropped on read —
+  // releasing ownership to the repository instead of planning a removal.
+  const dropRetiredOutputs = <O extends { readonly resourceId: string }>(
+    outputs: ReadonlyArray<O>,
+  ) => outputs.filter((output) => output.resourceId !== "setup:vite-plus-github-actions");
+  const currentLock =
+    rawLock === undefined
+      ? undefined
+      : { ...rawLock, outputs: dropRetiredOutputs(rawLock.outputs) };
+  const currentState =
+    rawState === undefined
+      ? undefined
+      : { ...rawState, outputs: dropRetiredOutputs(rawState.outputs) };
 
   yield* validateReservedPaths(projectDir, reservedPaths, [
     ...(currentLock?.outputs ?? []),
@@ -1601,6 +1496,8 @@ export const planProjectSkills = Effect.fn("planProjectSkills")(function* (optio
     ...(effectSource === undefined ? {} : { effectSource }),
     ...(effectTsgo === undefined ? {} : { effectTsgo }),
     ...(vitePlusHooks === undefined ? {} : { vitePlusHooks }),
+    ...(vitePlusWorkflow === undefined ? {} : { vitePlusWorkflow }),
+    ...(worktrunkConfig === undefined ? {} : { worktrunkConfig }),
     nextLock,
     nextState: planned.nextState,
     metadataChanged:
@@ -1627,7 +1524,9 @@ const operationalChangeCount = (plan: SkillPlan): number =>
   plan.actions.filter((action) => action.action !== "unchanged").length +
   (plan.effectSource?.action === "sync" ? 1 : 0) +
   (plan.effectTsgo !== undefined && !plan.effectTsgo.alreadyPatched ? 1 : 0) +
-  (plan.vitePlusHooks?.action === "configure" ? 1 : 0);
+  (plan.vitePlusHooks?.action === "configure" ? 1 : 0) +
+  (plan.vitePlusWorkflow?.action === "scaffold" ? 1 : 0) +
+  (plan.worktrunkConfig?.action === "scaffold" ? 1 : 0);
 
 const plannedChangeCount = (plan: SkillPlan): number => {
   const operational = operationalChangeCount(plan);
@@ -1658,6 +1557,12 @@ export const printSkillPlan = Effect.fn("printSkillPlan")(function* (plan: Skill
   if (plan.vitePlusHooks?.action === "configure") {
     yield* printDetail(`+ Vite+ hooks → ${plan.vitePlusHooks.hooksPath}`);
   }
+  if (plan.vitePlusWorkflow?.action === "scaffold") {
+    yield* printDetail(`+ scaffold check workflow → ${plan.vitePlusWorkflow.path}`);
+  }
+  if (plan.worktrunkConfig?.action === "scaffold") {
+    yield* printDetail(`+ scaffold Worktrunk config → ${plan.worktrunkConfig.path}`);
+  }
   if (operationalChangeCount(plan) === 0 && plan.metadataChanged) {
     yield* printDetail("+ Dev kit metadata");
   }
@@ -1952,6 +1857,8 @@ export const runProjectSkillPlan = Effect.fn("runProjectSkillPlan")(function* (
     effectSource: plan.effectSource,
     effectTsgo: plan.effectTsgo,
     vitePlusHooks: plan.vitePlusHooks,
+    vitePlusWorkflow: plan.vitePlusWorkflow,
+    worktrunkConfig: plan.worktrunkConfig,
     nextLock: plan.nextLock,
     nextState: plan.nextState,
   });
@@ -1960,6 +1867,8 @@ export const runProjectSkillPlan = Effect.fn("runProjectSkillPlan")(function* (
     effectSource: replanned.effectSource,
     effectTsgo: replanned.effectTsgo,
     vitePlusHooks: replanned.vitePlusHooks,
+    vitePlusWorkflow: replanned.vitePlusWorkflow,
+    worktrunkConfig: replanned.worktrunkConfig,
     nextLock: replanned.nextLock,
     nextState: replanned.nextState,
   });
@@ -1981,9 +1890,27 @@ export const runProjectSkillPlan = Effect.fn("runProjectSkillPlan")(function* (
       if (replanned.vitePlusHooks !== undefined) {
         yield* applyVitePlusHooksPlan(replanned.vitePlusHooks);
       }
+      if (replanned.vitePlusWorkflow !== undefined) {
+        yield* applyScaffoldPlan(replanned.vitePlusWorkflow);
+      }
+      if (replanned.worktrunkConfig !== undefined) {
+        yield* applyScaffoldPlan(replanned.worktrunkConfig);
+      }
       yield* applyPlannedSkillChanges(replanned);
     }),
   );
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+
+  // Catalog checkouts moved to the machine-global cache; drop the regenerable
+  // project-local copies left behind by earlier dev-kit versions.
+  yield* fs
+    .remove(path.join(plan.projectDir, ".dev-kit", "cache", "catalog"), {
+      force: true,
+      recursive: true,
+    })
+    .pipe(Effect.ignore);
+  yield* maybePruneGlobalCache().pipe(Effect.ignore);
   yield* printStatus(
     "success",
     changes === 0 && !replanned.metadataChanged ? "Dev kit up to date" : "Dev kit ready",

package/src/vite-plus-workflow.ts

@@ -0,0 +1,82 @@
+import { Effect, Schema } from "effect";
+
+import { readDirectDependencyNames } from "./project-package.ts";
+import { planScaffold, readScaffoldTemplate, replaceUniqueTemplateMarker } from "./scaffold.ts";
+import { validateInstalledVitePlus } from "./vite-plus-dependency.ts";
+
+export const VITE_PLUS_GITHUB_ACTIONS_PATH = ".github/workflows/check.yml";
+export const VITE_PLUS_GITHUB_ACTIONS_TEMPLATE = "templates/vite-plus/github-actions-check.yml";
+
+export class VitePlusWorkflowSupportError extends Schema.TaggedError<VitePlusWorkflowSupportError>()(
+  "VitePlusWorkflowSupportError",
+  { message: Schema.String },
+) {}
+
+const LOCKED_DEV_KIT_COMMAND =
+  "bun ./node_modules/@danieljvdm/dev-kit/bin/dev-kit.mjs apply --locked";
+
+export const renderVitePlusWorkflowTemplate = (
+  template: string,
+  options: { readonly devKitCommand?: string } = {},
+): string => {
+  const devKitCommand = options.devKitCommand;
+
+  return devKitCommand === undefined || devKitCommand === LOCKED_DEV_KIT_COMMAND
+    ? template
+    : replaceUniqueTemplateMarker(template, LOCKED_DEV_KIT_COMMAND, devKitCommand);
+};
+
+export const validateVitePlusWorkflowSupport = Effect.fn("validateVitePlusWorkflowSupport")(
+  function* (projectDir: string, packageRoot: string, typescriptPackage: string) {
+    const dependencies = yield* readDirectDependencyNames(projectDir);
+    const required = new Set(["effect", "@effect/tsgo", typescriptPackage]);
+
+    yield* validateInstalledVitePlus(projectDir).pipe(
+      Effect.mapError((error) => VitePlusWorkflowSupportError.make({ message: error.message })),
+    );
+
+    if (projectDir !== packageRoot) required.add("@danieljvdm/dev-kit");
+    const missing = [...required].filter((dependency) => !dependencies.includes(dependency));
+
+    if (missing.length > 0) {
+      return yield* VitePlusWorkflowSupportError.make({
+        message: `setup.vitePlus.workflow requires direct dependencies: ${missing.join(", ")}`,
+      });
+    }
+  },
+);
+
+export const planVitePlusWorkflow = (options: {
+  readonly packageRoot: string;
+  readonly projectDir: string;
+  readonly effectTsgoEnabled: boolean;
+  readonly typescriptPackage: string;
+}) =>
+  planScaffold({
+    projectDir: options.projectDir,
+    path: VITE_PLUS_GITHUB_ACTIONS_PATH,
+    content: Effect.gen(function* () {
+      if (!options.effectTsgoEnabled) {
+        return yield* VitePlusWorkflowSupportError.make({
+          message:
+            "setup.vitePlus.workflow requires setup.effectTsgo.enabled so the scaffolded workflow's typecheck uses the Effect-patched compiler",
+        });
+      }
+      yield* validateVitePlusWorkflowSupport(
+        options.projectDir,
+        options.packageRoot,
+        options.typescriptPackage,
+      );
+      const template = yield* readScaffoldTemplate(
+        options.packageRoot,
+        VITE_PLUS_GITHUB_ACTIONS_TEMPLATE,
+      );
+
+      return renderVitePlusWorkflowTemplate(
+        template,
+        options.projectDir === options.packageRoot
+          ? { devKitCommand: "./bin/dev-kit.mjs apply --locked" }
+          : {},
+      );
+    }),
+  });

package/src/vite-plus.js

@@ -1,5 +1,5 @@
 import { recommendedOxfmtConfig } from "./oxfmt.js";
-import { recommendedOxlintConfig } from "./oxlint.js";
+import { createAbsoluteImportsOxlintOverride, recommendedOxlintConfig } from "./oxlint.js";
 import { devKitToolIgnorePatterns } from "./tool-ignore-patterns.js";
 
 export { devKitToolIgnorePatterns } from "./tool-ignore-patterns.js";
@@ -58,6 +58,12 @@ const createTypecheckTask = (options) => {
 /** Build composable quality defaults for a project-owned Vite+ config. */
 export const createRecommendedVitePlusConfig = (options = {}) => {
   const ignorePatterns = [...devKitToolIgnorePatterns, ...(options.ignorePatterns ?? [])];
+  const lintOverrides = options.absoluteImports
+    ? [
+        ...recommendedOxlintConfig.overrides,
+        createAbsoluteImportsOxlintOverride(options.absoluteImports),
+      ]
+    : recommendedOxlintConfig.overrides;
 
   return {
     staged: {
@@ -70,6 +76,7 @@ export const createRecommendedVitePlusConfig = (options = {}) => {
     lint: {
       ...recommendedOxlintConfig,
       ignorePatterns,
+      overrides: lintOverrides,
     },
     run: {
       tasks: {

package/src/vite-plus.ts

@@ -1,7 +1,12 @@
 import { recommendedOxfmtConfig } from "./oxfmt.ts";
-import { recommendedOxlintConfig } from "./oxlint.ts";
+import {
+  type AbsoluteImportsOptions,
+  createAbsoluteImportsOxlintOverride,
+  recommendedOxlintConfig,
+} from "./oxlint.ts";
 import { devKitToolIgnorePatterns } from "./tool-ignore-patterns.ts";
 
+export type { AbsoluteImportsOptions } from "./oxlint.ts";
 export { devKitToolIgnorePatterns } from "./tool-ignore-patterns.ts";
 
 export type VitePlusTypecheckOptions =
@@ -16,6 +21,8 @@ export type VitePlusTypecheckOptions =
     };
 
 export type RecommendedVitePlusConfigOptions = {
+  /** Enforce path-alias imports (no `../`) inside the given globs. */
+  readonly absoluteImports?: AbsoluteImportsOptions;
   /** Additional project-owned generated or vendored paths. */
   readonly ignorePatterns?: ReadonlyArray<string>;
   readonly typecheck?: VitePlusTypecheckOptions;
@@ -79,6 +86,12 @@ const createTypecheckTask = (options: VitePlusTypecheckOptions | undefined) => {
  */
 export const createRecommendedVitePlusConfig = (options: RecommendedVitePlusConfigOptions = {}) => {
   const ignorePatterns = [...devKitToolIgnorePatterns, ...(options.ignorePatterns ?? [])];
+  const lintOverrides = options.absoluteImports
+    ? [
+        ...recommendedOxlintConfig.overrides,
+        createAbsoluteImportsOxlintOverride(options.absoluteImports),
+      ]
+    : recommendedOxlintConfig.overrides;
 
   return {
     staged: {
@@ -91,6 +104,7 @@ export const createRecommendedVitePlusConfig = (options: RecommendedVitePlusConf
     lint: {
       ...recommendedOxlintConfig,
       ignorePatterns,
+      overrides: lintOverrides,
     },
     run: {
       tasks: {