@danieljvdm/dev-kit 0.3.2 → 0.4.0

package/README.md

@@ -309,16 +309,21 @@ 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+
+## Oxlint and Oxfmt configurations
 
-Dev Kit exports a typed, composable set of high-signal Oxlint rules for Vite+
-projects:
+Dev Kit exports one typed Oxlint ruleset and one typed Oxfmt configuration for
+both standalone Oxc projects and Vite+ projects. A Vite+ project composes them
+in `vite.config.ts`:
 
 ```ts
 import { recommendedOxlintConfig } from "@danieljvdm/dev-kit/oxlint";
+import { recommendedOxfmtConfig } from "@danieljvdm/dev-kit/oxfmt";
 import { defineConfig } from "vite-plus";
 
 export default defineConfig({
+  fmt: {
+    ...recommendedOxfmtConfig,
+  },
   lint: {
     extends: [recommendedOxlintConfig],
     rules: {
@@ -329,7 +334,38 @@ export default defineConfig({
 ```
 
 Use `lint.extends` rather than a shallow object spread so Vite+ composes the
-nested plugin and rule configuration correctly.
+nested plugin and rule configuration correctly. Oxfmt has no `extends`, so
+spread its configuration before project-local formatter options.
+
+Standalone projects import the same objects from their native config files:
+
+```ts
+// oxlint.config.ts
+import { recommendedOxlintConfig } from "@danieljvdm/dev-kit/oxlint";
+import { defineConfig } from "oxlint";
+
+export default defineConfig({
+  extends: [recommendedOxlintConfig],
+});
+```
+
+```ts
+// oxfmt.config.ts
+import { recommendedOxfmtConfig } from "@danieljvdm/dev-kit/oxfmt";
+import { defineConfig } from "oxfmt";
+
+export default defineConfig({
+  ...recommendedOxfmtConfig,
+});
+```
+
+The Oxlint preset also registers the shared `effect` JavaScript plugin. Effect
+projects opt into its rules in path-specific overrides, for example
+`effect/no-effect-run`, `effect/no-unsafe-promise`, and
+`effect/no-untyped-throw`. The package exports the plugin directly from
+`@danieljvdm/dev-kit/oxlint-plugin-effect` for configurations that do not
+extend the recommended preset. Strict workflow, Atom, and boundary rules remain
+consumer-scoped because application and host boundaries differ by repository.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danieljvdm/dev-kit",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "private": false,
   "type": "module",
   "description": "Declarative project development toolkit with portable agent skills.",
@@ -23,6 +23,14 @@
     "./oxlint": {
       "types": "./src/oxlint.ts",
       "default": "./src/oxlint.js"
+    },
+    "./oxfmt": {
+      "types": "./src/oxfmt.ts",
+      "default": "./src/oxfmt.js"
+    },
+    "./oxlint-plugin-effect": {
+      "types": "./src/oxlint-plugin-effect.d.ts",
+      "default": "./src/oxlint-plugin-effect.js"
     }
   },
   "files": [
@@ -64,14 +72,24 @@
     "@effect/tsgo": "0.24.3",
     "@effect/vitest": "4.0.0-beta.102",
     "@types/node": "25.9.1",
+    "oxfmt": "0.60.0",
+    "oxlint": "1.75.0",
     "typescript": "7.0.2",
     "vite-plus": "0.2.6",
     "vitest": "4.1.10"
   },
   "peerDependencies": {
+    "oxfmt": ">=0.60.0 <0.61.0",
+    "oxlint": ">=1.75.0 <2.0.0",
     "vite-plus": ">=0.2.6 <0.3.0"
   },
   "peerDependenciesMeta": {
+    "oxfmt": {
+      "optional": true
+    },
+    "oxlint": {
+      "optional": true
+    },
     "vite-plus": {
       "optional": true
     }

package/skills/dev-kit/SKILL.md

@@ -156,16 +156,19 @@ 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+
+## Oxlint and Oxfmt configurations
 
-For Vite+ projects, compose the package's typed recommended Oxlint preset with
-project-specific lint configuration:
+Use Dev Kit's canonical Oxlint and Oxfmt objects in Vite+ projects:
 
 ```ts
 import { recommendedOxlintConfig } from "@danieljvdm/dev-kit/oxlint";
+import { recommendedOxfmtConfig } from "@danieljvdm/dev-kit/oxfmt";
 import { defineConfig } from "vite-plus";
 
 export default defineConfig({
+  fmt: {
+    ...recommendedOxfmtConfig,
+  },
   lint: {
     extends: [recommendedOxlintConfig],
     rules: {
@@ -176,14 +179,24 @@ export default defineConfig({
 ```
 
 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.
+rule maps correctly. Oxfmt has no inheritance mechanism, so spread its object
+before project-local options. Standalone `oxlint.config.ts` uses the same
+`extends: [recommendedOxlintConfig]`; standalone `oxfmt.config.ts` spreads the
+same `recommendedOxfmtConfig`.
+
+The Oxlint preset registers Dev Kit's shared Effect plugin as `effect`, but
+does not enable its scope-sensitive rules globally. Effect projects should
+enable rules such as `effect/no-effect-run`, `effect/no-unsafe-promise`, and
+`effect/no-untyped-throw` only in Effect-owned code, with explicit exceptions
+for tests and host boundaries. The stricter `effect/no-async-workflow`,
+`effect/no-promise-atom-mode`, and `effect/no-sync-boundary-decode` rules also
+need consumer-owned scopes. Keep repository-specific paths and platform 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. 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.
+contributions deliberately. The Oxlint and Oxfmt configurations are composable
+package exports, not manifest-managed outputs. Treat broader setup tasks as
+future manifest capabilities until the installed CLI exposes them.

package/skills/effect-ts/references/guide-cli.md

@@ -99,7 +99,8 @@ Run the narrowest meaningful checks:
 
 - Confirm that every TypeScript entrypoint named by `package.json` belongs to
   one checked TypeScript project.
-- `bun run check:scripts` for root scripts.
+- The repository's root `check` or typecheck script when the entrypoint belongs
+  to the root project.
 - Package-level `bun run check` when the script lives under an app/package and is included in that TS config.
 - The command's `--help` path.
 - A dry-run or harmless invalid-input path that loads the entrypoint and

package/src/oxfmt.js

@@ -0,0 +1,18 @@
+/**
+ * Runtime form of the typed preset declared in oxfmt.ts.
+ *
+ * This file is intentionally plain JavaScript because Node does not strip
+ * TypeScript from packages in node_modules when tools load their config.
+ */
+export const recommendedOxfmtConfig = {
+  arrowParens: "always",
+  endOfLine: "lf",
+  printWidth: 100,
+  semi: true,
+  singleQuote: false,
+  sortImports: true,
+  sortPackageJson: true,
+  tabWidth: 2,
+  trailingComma: "all",
+  useTabs: false,
+};

package/src/oxfmt.ts

@@ -0,0 +1,22 @@
+import type { OxfmtConfig } from "oxfmt";
+
+/**
+ * Canonical formatting defaults for standalone Oxfmt and Vite+ projects.
+ *
+ * Oxfmt does not support config inheritance. Spread this object into a
+ * standalone Oxfmt config or Vite+'s `fmt` block before local overrides.
+ */
+export const recommendedOxfmtConfig = {
+  arrowParens: "always",
+  endOfLine: "lf",
+  printWidth: 100,
+  semi: true,
+  singleQuote: false,
+  sortImports: true,
+  sortPackageJson: true,
+  tabWidth: 2,
+  trailingComma: "all",
+  useTabs: false,
+} satisfies OxfmtConfig;
+
+export type RecommendedOxfmtConfig = typeof recommendedOxfmtConfig;

package/src/oxlint-plugin-effect.d.ts

@@ -0,0 +1,17 @@
+interface EffectOxlintRule {
+  readonly meta: {
+    readonly type: "problem";
+    readonly docs: { readonly description: string };
+    readonly messages: Readonly<Record<string, string>>;
+  };
+  readonly create: (context: {
+    report(descriptor: { node: unknown; messageId: string }): void;
+  }) => Readonly<Record<string, (node: unknown) => void>>;
+}
+
+declare const effectOxlintPlugin: {
+  readonly meta: { readonly name: "dev-kit-effect" };
+  readonly rules: Readonly<Record<string, EffectOxlintRule>>;
+};
+
+export default effectOxlintPlugin;

package/src/oxlint-plugin-effect.js

@@ -0,0 +1,166 @@
+const noUntypedThrow = {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow throw statements from Effect-owned application code." },
+    messages: {
+      noUntypedThrow:
+        "Do not throw from Effect-owned code. Fail with a tagged error in the Effect error channel.",
+    },
+  },
+  create(context) {
+    return {
+      ThrowStatement(node) {
+        context.report({ node, messageId: "noUntypedThrow" });
+      },
+    };
+  },
+};
+
+const noPromiseAtomMode = {
+  meta: {
+    type: "problem",
+    docs: { description: "Require Effect Atom AsyncResult mode for React mutations." },
+    messages: {
+      noPromiseAtomMode:
+        'Do not use Effect Atom mode: "promise". Compose the workflow with Atom.fn and render its AsyncResult.',
+    },
+  },
+  create(context) {
+    return {
+      Property(node) {
+        const key = node.key;
+        const value = node.value;
+        const isMode =
+          (key.type === "Identifier" && key.name === "mode") ||
+          (key.type === "Literal" && key.value === "mode");
+        if (isMode && value.type === "Literal" && value.value === "promise") {
+          context.report({ node, messageId: "noPromiseAtomMode" });
+        }
+      },
+    };
+  },
+};
+
+const noEffectRun = {
+  meta: {
+    type: "problem",
+    docs: { description: "Keep Effect runtime execution at explicit host entry points." },
+    messages: {
+      noEffectRun:
+        "Do not execute Effect with Effect.run* inside application code. Return or compose the Effect instead.",
+    },
+  },
+  create(context) {
+    return {
+      MemberExpression(node) {
+        if (
+          node.object.type === "Identifier" &&
+          node.object.name === "Effect" &&
+          !node.computed &&
+          node.property.type === "Identifier" &&
+          node.property.name.startsWith("run")
+        ) {
+          context.report({ node, messageId: "noEffectRun" });
+        }
+      },
+    };
+  },
+};
+
+const noUnsafePromise = {
+  meta: {
+    type: "problem",
+    docs: { description: "Require rejecting Promise boundaries to preserve typed failures." },
+    messages: {
+      noEffectPromise:
+        "Effect.promise turns rejection into a defect. Use Effect.tryPromise and map a tagged boundary error.",
+      noPromiseConstructor:
+        "Do not construct workflow Promises directly. Use Effect async/scheduling/concurrency operators.",
+    },
+  },
+  create(context) {
+    return {
+      MemberExpression(node) {
+        if (
+          node.object.type === "Identifier" &&
+          node.object.name === "Effect" &&
+          !node.computed &&
+          node.property.type === "Identifier" &&
+          node.property.name === "promise"
+        ) {
+          context.report({ node, messageId: "noEffectPromise" });
+        }
+      },
+      NewExpression(node) {
+        if (node.callee.type === "Identifier" && node.callee.name === "Promise") {
+          context.report({ node, messageId: "noPromiseConstructor" });
+        }
+      },
+    };
+  },
+};
+
+const noAsyncWorkflow = {
+  meta: {
+    type: "problem",
+    docs: { description: "Keep business workflows in Effect instead of async functions." },
+    messages: {
+      noAsyncWorkflow:
+        "Do not implement application workflows as async functions. Return an Effect and capture foreign Promises with Effect.tryPromise.",
+    },
+  },
+  create(context) {
+    const check = (node) => {
+      if (!node.async) return;
+      const parent = node.parent;
+      const isCapturedTryThunk =
+        parent?.type === "Property" &&
+        ((parent.key.type === "Identifier" && parent.key.name === "try") ||
+          (parent.key.type === "Literal" && parent.key.value === "try"));
+      if (!isCapturedTryThunk) context.report({ node, messageId: "noAsyncWorkflow" });
+    };
+    return {
+      ArrowFunctionExpression: check,
+      FunctionDeclaration: check,
+      FunctionExpression: check,
+    };
+  },
+};
+
+const noSyncBoundaryDecode = {
+  meta: {
+    type: "problem",
+    docs: { description: "Prevent external values from becoming synchronous schema defects." },
+    messages: {
+      noSyncBoundaryDecode:
+        "Do not synchronously decode route, persisted, or native input. Use Schema.decodeUnknownEffect/Option and handle the typed failure.",
+    },
+  },
+  create(context) {
+    return {
+      MemberExpression(node) {
+        if (
+          node.object.type === "Identifier" &&
+          node.object.name === "Schema" &&
+          !node.computed &&
+          node.property.type === "Identifier" &&
+          node.property.name === "decodeUnknownSync"
+        ) {
+          context.report({ node, messageId: "noSyncBoundaryDecode" });
+        }
+      },
+    };
+  },
+};
+
+export default {
+  meta: { name: "dev-kit-effect" },
+  rules: {
+    "no-async-workflow": noAsyncWorkflow,
+    "no-effect-run": noEffectRun,
+    "no-promise-atom-mode": noPromiseAtomMode,
+    "no-sync-boundary-decode": noSyncBoundaryDecode,
+    "no-untyped-throw": noUntypedThrow,
+    "no-unsafe-promise": noUnsafePromise,
+  },
+};

package/src/oxlint.js

@@ -8,6 +8,12 @@ export const recommendedOxlintConfig = {
   options: {
     typeAware: true,
   },
+  jsPlugins: [
+    {
+      name: "effect",
+      specifier: "@danieljvdm/dev-kit/oxlint-plugin-effect",
+    },
+  ],
   plugins: ["import", "react", "vitest"],
   rules: {
     eqeqeq: "error",

package/src/oxlint.ts

@@ -1,15 +1,22 @@
-import type { OxlintConfig } from "vite-plus/lint";
+import type { OxlintConfig } from "oxlint";
 
 /**
- * High-signal Oxlint defaults for TypeScript projects using Vite+.
+ * High-signal Oxlint defaults for TypeScript projects.
  *
- * Extend this object from `lint.extends` so project-local plugins, rules, and
- * overrides compose without losing nested configuration.
+ * Extend this object from standalone Oxlint's `extends`, or from Vite+'s
+ * `lint.extends`, so project-local plugins, rules, and overrides compose
+ * without losing nested configuration.
  */
 export const recommendedOxlintConfig = {
   options: {
     typeAware: true,
   },
+  jsPlugins: [
+    {
+      name: "effect",
+      specifier: "@danieljvdm/dev-kit/oxlint-plugin-effect",
+    },
+  ],
   plugins: ["import", "react", "vitest"],
   rules: {
     eqeqeq: "error",