traits 0.3.0 → 0.5.0

package/TraitsConfig.ts

@@ -0,0 +1,57 @@
+import type { NodeServices } from "@effect/platform-node"
+import { Array, Effect, Layer, Path, pipe, Schema as S, Semaphore } from "effect"
+import { DecisionModel, LanguageModel } from "effect/ai"
+import { HttpClient } from "effect/http"
+
+import { getWorktreeRoot } from "./_util/Git.ts"
+import { TraitsContext } from "./TraitsContext.ts"
+
+export type TraitsConfig = typeof TraitsConfig.Type
+export const TraitsConfig = S.Struct({
+  excludeGitignored: S.Boolean.pipe(S.optional).annotate({
+    description: "Exclude Git-ignored files from checks by default. Set false to disable the Git file-set filter."
+  }),
+  excludes: S.Array(S.NonEmptyString).pipe(S.optional).annotate({
+    description:
+      "Filenames or native filesystem glob patterns excluded from trait checks, relative to traits.ts or absolute. Use directory/** to exclude a subtree. Bare directories are not expanded; escape glob characters in literal filenames using native glob syntax."
+  }),
+  layerDecisionModel: S.declare(
+    (
+      value
+    ): value is Layer.Layer<DecisionModel.DecisionModel, any, NodeServices.NodeServices | HttpClient.HttpClient> =>
+      Layer.isLayer(value)
+  ),
+  layerLanguageModel: S.declare(
+    (
+      value
+    ): value is Layer.Layer<LanguageModel.LanguageModel, any, NodeServices.NodeServices | HttpClient.HttpClient> =>
+      Layer.isLayer(value)
+  )
+})
+
+export const layer = Effect.gen(function* () {
+  const path = yield* Path.Path
+  const configRoot = yield* getWorktreeRoot
+  const url = yield* path.toFileUrl(path.join(configRoot, "traits.ts"))
+  const module = yield* Effect.promise(() => import(url.href))
+  const config = yield* pipe(module.default, S.decodeUnknownEffect(TraitsConfig))
+  return Layer.mergeAll(
+    // oxlint-disable-next-line effecttsgo/any-unknown-in-error-context
+    config.layerDecisionModel.pipe(Layer.orDie),
+    // oxlint-disable-next-line effecttsgo/any-unknown-in-error-context
+    config.layerLanguageModel.pipe(Layer.orDie),
+    Layer.effect(
+      TraitsContext,
+      Effect.gen(function* () {
+        const excludes = Array.appendAll(
+          Array.flatMap([".git", ".worktrees"], (directory) => [`**/${directory}`, `**/${directory}/**`]),
+          Array.map(config.excludes ?? [], (pattern) =>
+            path.isAbsolute(pattern) ? path.relative(configRoot, pattern) : pattern
+          )
+        )
+        const semaphore = yield* Semaphore.make(4)
+        return { configRoot, excludeGitignored: config.excludeGitignored ?? true, excludes, semaphore }
+      })
+    )
+  )
+}).pipe(Layer.unwrap)

package/TraitsContext.ts

@@ -0,0 +1,11 @@
+import { Context, Semaphore } from "effect"
+
+export class TraitsContext extends Context.Service<
+  TraitsContext,
+  {
+    readonly configRoot: string
+    readonly excludeGitignored: boolean
+    readonly excludes: ReadonlyArray<string>
+    readonly semaphore: Semaphore.Semaphore
+  }
+>()("traits/TraitsContext") {}

package/_util/Approval.ts

@@ -0,0 +1,59 @@
+import { Effect, Option, Schema as S, String } from "effect"
+import { McpSchema, McpServer } from "effect/ai"
+
+export type Approval = typeof Approval.Type
+export const Approval = S.TaggedUnion({
+  Approved: {},
+  ApprovalRequired: { message: S.String },
+  RevisionRequired: { feedback: S.String },
+  Declined: {}
+})
+
+export const request = Effect.fn("Approval.request")(function* (options: {
+  readonly message: string
+  readonly approved?: boolean | undefined
+}) {
+  const client = yield* Effect.serviceOption(McpSchema.McpServerClient).pipe(Effect.map(Option.getOrUndefined))
+  const supportsForm =
+    client !== undefined &&
+    client.clientCapabilities.elicitation !== undefined &&
+    (client.clientCapabilities.elicitation.form !== undefined ||
+      client.clientCapabilities.elicitation.url === undefined)
+  const globalForms =
+    client !== undefined &&
+    (String.toLowerCase(client.clientInfo.name) === "opencode" ||
+      typeof client.requestMetadata?.["ai.opencode/sessionID"] === "string")
+
+  if (client === undefined || !supportsForm || globalForms) {
+    return options.approved === true
+      ? Approval.cases.Approved.make({})
+      : Approval.cases.ApprovalRequired.make({ message: options.message })
+  }
+
+  const response = yield* McpServer.elicit({
+    message: options.message,
+    schema: S.Struct({
+      decision: S.Literals(["approve", "revise", "skip"]).annotate({
+        description: "Approve this exact proposal, request a revision, or skip it."
+      }),
+      feedback: S.String.pipe(S.optionalKey).annotate({ description: "Optional revision or alternative wording." })
+    })
+  }).pipe(
+    Effect.provideService(McpSchema.McpServerClient, client),
+    Effect.catchTags({
+      ElicitationDeclined: (error) => (error.cause === undefined ? Effect.undefined : error)
+    })
+  )
+  if (response === undefined || response.decision === "skip") return Approval.cases.Declined.make({})
+  if (response.decision === "revise" || (response.feedback !== undefined && String.trim(response.feedback) !== "")) {
+    const feedback = response.feedback === undefined ? "" : String.trim(response.feedback)
+    const guidance = String.stripMargin(`
+    | Ask the user for revision details using an interactive question with free-text input.
+    | Keep this proposal pending; do not infer approval or cancel it because of a related follow-up task.
+    `)
+    return Approval.cases.RevisionRequired.make({
+      feedback: feedback !== "" ? feedback : guidance
+    })
+  }
+  return Approval.cases.Approved.make({})
+})

package/_util/Git.ts

@@ -0,0 +1,25 @@
+import { Data, Effect, Path, String } from "effect"
+import { ChildProcess, ChildProcessSpawner } from "effect/process"
+
+export class GitRootError extends Data.TaggedError("GitRootError")<{ readonly message: string }> {}
+
+const resolveRoot = Effect.fn("Git.resolveRoot")(function* (command: ChildProcess.Command) {
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner
+  return yield* spawner.string(command).pipe(
+    Effect.map(String.trim),
+    Effect.filterOrFail(
+      String.isNonEmpty,
+      () => new GitRootError({ message: "Run from inside a Git repository or worktree" })
+    )
+  )
+})
+
+/** The current checkout root, including when running in a linked worktree. */
+export const getWorktreeRoot = resolveRoot(ChildProcess.make`git rev-parse --show-toplevel`)
+
+/** The main checkout root, shared by its linked worktrees. */
+export const getGitRoot = Effect.gen(function* () {
+  const path = yield* Path.Path
+  const gitDir = yield* resolveRoot(ChildProcess.make`git rev-parse --path-format=absolute --git-common-dir`)
+  return path.dirname(gitDir)
+})

package/_util/TraitsConfigProvider.ts

@@ -0,0 +1,22 @@
+import { Array, ConfigProvider, Effect, FileSystem, Path } from "effect"
+
+import { getGitRoot, getWorktreeRoot } from "./Git.ts"
+
+export const layer = ConfigProvider.layerAdd(
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem
+    const path = yield* Path.Path
+    const worktreeRoot = yield* getWorktreeRoot
+    const gitRoot = yield* getGitRoot
+    const files = Array.dedupe([path.join(worktreeRoot, ".env"), path.join(gitRoot, ".env")])
+    let provider = ConfigProvider.fromUnknown({})
+    for (const file of files) {
+      if (yield* fs.exists(file)) {
+        provider = yield* ConfigProvider.fromDotEnv({ path: file }).pipe(
+          Effect.map((value) => ConfigProvider.orElse(provider, value))
+        )
+      }
+    }
+    return provider
+  }).pipe(Effect.withSpan("TraitsConfigProvider.load"))
+)

package/_util/TraitsTelemetry.ts

@@ -0,0 +1,20 @@
+import { Layer, pipe, String } from "effect"
+import { Url } from "effect/http"
+import { OtlpLogger, OtlpSerialization, OtlpTracer } from "effect/observability"
+
+import PackageJson from "../package.json" with { type: "json" }
+
+export const layer = (endpoint: URL | undefined) => {
+  if (endpoint === undefined) return Layer.empty
+  const url = (signal: string) =>
+    pipe(
+      endpoint,
+      Url.setPathname(`${pipe(endpoint.pathname, String.replace(/\/$/, ""))}/v1/${signal}`),
+      Url.setHash("")
+    ).href
+  const resource = { serviceName: "traits", serviceVersion: PackageJson.version }
+  return Layer.mergeAll(
+    OtlpTracer.layer({ url: url("traces"), resource }),
+    OtlpLogger.layer({ url: url("logs"), resource })
+  ).pipe(Layer.provide(OtlpSerialization.layerJson))
+}