docks-kit 0.14.4 → 0.15.0

package/AGENTS.md

@@ -21,7 +21,7 @@ Bun source.
 |------|---------|
 | `docks-kit` | CLI launcher: on supported hosts, runs the platform binary in `cli/dist/` only when its `--version` matches `package.json`, otherwise Bun-from-source (auto-installs Bun + `node_modules`). Unsupported hosts fail before source fallback. No-Bun recovery is the standalone platform release binary |
 | `cli/src/engine-native/` | EngineNative implementation for `sync`, `model`, and `toolchain`; idempotent, flag-gated for destructive reconciliation |
-| `cli/` | Effect-TS CLI + bundled docs topics |
+| `cli/` | Effect 4 beta CLI + bundled docs topics |
 | `SoT/models.json` | Kit-verified Claude and Codex model catalog |
 | `SoT/toolchain.json` | Toolchain floors manifest (verified pins consumed by EngineNative) |
 | `SoT/.claude/bin/` | Dependency-free Bun runtime programs for Claude's statusline, SessionStart, and Notification |
@@ -51,6 +51,8 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`), see the matching SoT d
 
 - **Idempotent operations.** Every EngineNative sync step must be safe to re-run. Settings merges, plugin installs, and marketplace adds are all idempotent — re-running with no SoT changes is a no-op.
 - **Removed bash engine.** The bash engine was removed after the `bash-engine-final` tag. `DOCKS_KIT_ENGINE=bash` must fail with the removed-engine message; engine bugs are fixed forward in EngineNative.
+- **Effect 4 CLI stack.** The CLI pins `effect@4.0.0-beta.107` (including `effect/unstable/cli`), `@effect/platform-bun@4.0.0-beta.107` (`BunServices.layer`, `BunRuntime.runMain`), `@effect/vitest@4.0.0-beta.107`, and `vitest@4.1.10` (required by the `@effect/vitest` peer range). `@effect/cli` and `@effect/platform` are removed and must not be reintroduced.
+- **Effect skill routing.** Effect work in this checkout must use the `effect-v4` skill from the already-enabled `effect-kit@docks` plugin; `effect-ts-setup`, `effect-ts-port`, and `effect-ts-specialist` target Effect 3.x and do not apply. Verify migration and API call shapes against the installed declarations under `node_modules/effect/dist/unstable/cli/`, never from memory or a mutable dist-tag.
 - **Targeted syncs.** `./docks-kit sync` accepts positional targets: `claude`, `codex`, and `agents`. Use the narrowest target that matches the SoT change (for example, `./docks-kit sync codex` for Codex-only config edits); targets can be combined with `--dry-run`, `--skip-bubblewrap` (skip optional bubblewrap bootstrap for the Codex Linux sandbox), `--skip-plugin-refresh` (install missing plugins without refreshing existing caches; used by `docks-kit update`), `--reconcile`, `--prune`, `--yes` (auto-accept toolchain prompts), and the deploy-time modifiers `--claude-compact-window=<tokens>` / `--claude-permissive` / `--claude-model=<m>` / `--claude-effort=<level>` / `--claude-advisor=<on|off|default>` / `--codex-model=<m>` / `--codex-effort=<level>` (see `CLAUDE.md` § Deploy-time modifiers).
 - **Additive by default.** Keys present in deployed config but absent from SoT are preserved on default sync. This protects user-only additions, but means drift accumulates — neither flag-less reset can clean it up. The one exception is the Claude `removed` manifest (`claude::_removed_manifest`), a curated list of unambiguous kit-owned artifacts that `claude::sync_removals` force-prunes on every sync, including the home-relative `~/.local/bin/session-relay` artifact installed outside `~/.claude`; see `CLAUDE.md` § Pruning stale artifacts.
 - **`--reconcile` / `--prune` are the kit-owned reconcile flags.** Orthogonal — `--reconcile` reconciles the settings layer (SoT-declared keys/tables/arrays win; user-only keys and nested objects are preserved; permissions arrays are replaced wholesale by SoT). `--prune` uninstalls kit-managed installations not in the SoT (plugins, marketplaces, and `~/.agents/skills/*` entries tracked in `~/.agents/.kit-managed-skills`). Combine for a full reset to SoT's kit-managed scope. User-only additions outside the kit's scope (custom env vars, mcpServers, manually-installed skills, third-party plugins not declared in SoT) are always preserved. Each tool's per-tool file documents the specific paths and diff recipes.

package/README.md

@@ -52,9 +52,15 @@ docks-kit docs [topic]                     self-documentation (9 topics)
 --help --version --wizard --completions    built-in
 ```
 
-The CLI is a typed front-end ([Effect-TS](https://effect.website) on Bun);
-all mutation runs through EngineNative in `cli/src/engine-native/`, with
-golden-regression coverage for dry-run output, mutation snapshots, and argv logs.
+The CLI is a typed Effect 4 beta front-end on Bun; all mutation runs through
+EngineNative in `cli/src/engine-native/`, with golden-regression coverage for
+dry-run output, mutation snapshots, and argv logs. Its dependency graph is
+`effect@4.0.0-beta.107` (including `effect/unstable/cli`),
+`@effect/platform-bun@4.0.0-beta.107` (`BunServices.layer` and
+`BunRuntime.runMain`), `@effect/vitest@4.0.0-beta.107`, and `vitest@4.1.10`
+(required by the `@effect/vitest` peer range). `@effect/cli` and
+`@effect/platform` are removed: neither has a 4.x release, the CLI API moved
+into core, and the standalone platform package was unused here.
 
 ### Key flags (`docks-kit sync`)
 
@@ -106,7 +112,7 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 | `SoT/toolchain.json` | Verified-version floors |
 | `cli/src/engine-native/` | EngineNative sync/model/toolchain implementation |
 | `cli/src/generated/sotPayload.ts` | Generated in-memory payload used by standalone and npm installs |
-| `cli/` | docks-kit CLI (Effect-TS on Bun) + bundled docs topics |
+| `cli/` | docks-kit CLI (Effect 4 beta on Bun) + bundled docs topics |
 | `docks-kit` | Launcher (binary → bun-from-source) |
 | `install.sh` | Global installer (Bun bootstrap + `bun add -g`) |
 | `docs/plans/` | Multi-commit work-item plans |
@@ -128,7 +134,7 @@ Details: `docks-kit docs platforms`.
 Tagging `cli-v*` builds four standalone binaries (Linux x64/arm64 and macOS
 x64/arm64) plus `SHA256SUMS` and attaches them to the GitHub release; npm
 publishes the exact package tarball through trusted publishing with OIDC provenance.
-Package `docks-kit` 0.14.4 bundles the CLI + generated payload, so npm releases
+Package `docks-kit` 0.15.0 bundles the CLI + generated payload, so npm releases
 are versioned config snapshots without shipping the authoring `SoT/` tree.
 
 ## Deeper docs

package/cli/docs/overview.md

@@ -16,7 +16,7 @@ AI-assisted dev environment on every machine.
 | `SoT/toolchain.json` | Verified-version floors for external tools (see `docks-kit docs toolchain`) |
 | `cli/src/generated/sotPayload.ts` | Deterministic generated payload embedded in standalone/npm execution |
 | `cli/src/engine-native/` | EngineNative mutation logic for sync/model/toolchain |
-| `cli/` | This CLI (Effect-TS on Bun) plus bundled docs |
+| `cli/` | This CLI (Effect 4 beta on Bun) plus bundled docs |
 | `docks-kit` | Launcher: version-matching compiled binary → bun-from-source, with Bun auto-install |
 
 ## Design rules

package/cli/src/argv.ts

@@ -0,0 +1,433 @@
+import { GlobalFlag } from "effect/unstable/cli"
+import { docsCommand } from "./commands/docs"
+import { modelCommand } from "./commands/model"
+import { modelsCommand } from "./commands/models"
+import { pluginsCommand } from "./commands/plugins"
+import { skillsCommand } from "./commands/skills"
+import { statusCommand } from "./commands/status"
+import { syncCommand } from "./commands/sync"
+import { toolchainCommand } from "./commands/toolchain"
+import { updateCommand } from "./commands/update"
+import {
+  advisorCatalog,
+  advisorFlagGrammar,
+  effortCatalog,
+  effortFlagGrammar
+} from "./efforts"
+import { KNOWN_CLAUDE_OPTIN_PLUGINS } from "./engine-native/parseArgs"
+import { modelCatalog, type Tool } from "./manifests"
+
+export type ArgvOutcome =
+  | { readonly kind: "reject"; readonly message: string; readonly exitCode: number }
+  | { readonly kind: "accept"; readonly args: ReadonlyArray<string> }
+
+interface FlagSurface {
+  readonly longFlags: ReadonlyArray<string>
+  readonly aliases: ReadonlyMap<string, string>
+  readonly valueFlags: ReadonlyArray<string>
+  readonly repeatableFlags: ReadonlyArray<string>
+}
+interface GlobalFlagSurface extends FlagSurface {
+  readonly actionFlags: ReadonlySet<string>
+}
+
+interface CommandValue {
+  readonly name: string
+}
+
+
+const flagMetadata = (
+  param: unknown
+): {
+  readonly name: string
+  readonly aliases: ReadonlyArray<string>
+  readonly takesValue: boolean
+  readonly repeatable: boolean
+} => {
+  let current = param
+  let repeatable = false
+
+  while (typeof current === "object" && current !== null) {
+    if (!("_tag" in current)) break
+    if (current._tag === "Variadic") repeatable = true
+    if (current._tag !== "Single") {
+      if (!("param" in current)) break
+      current = current.param
+      continue
+    }
+
+    if (!("name" in current) || typeof current.name !== "string") {
+      throw new Error("Effect CLI exposed a flag without a string name")
+    }
+    if (
+      !("aliases" in current) ||
+      !Array.isArray(current.aliases) ||
+      !current.aliases.every((alias) => typeof alias === "string")
+    ) {
+      throw new Error(`Effect CLI exposed invalid aliases for --${current.name}`)
+    }
+    if (
+      !("primitiveType" in current) ||
+      typeof current.primitiveType !== "object" ||
+      current.primitiveType === null ||
+      !("_tag" in current.primitiveType) ||
+      typeof current.primitiveType._tag !== "string"
+    ) {
+      throw new Error(`Effect CLI exposed no primitive type for --${current.name}`)
+    }
+    const aliases: ReadonlyArray<string> = current.aliases
+    return {
+      name: current.name,
+      aliases,
+      takesValue: current.primitiveType._tag !== "Boolean",
+      repeatable
+    }
+  }
+
+  throw new Error("Effect CLI exposed an unsupported flag parameter")
+}
+
+const flagSurface = (params: ReadonlyArray<unknown>): FlagSurface => {
+  const longFlags: Array<string> = []
+  const aliases = new Map<string, string>()
+  const valueFlags: Array<string> = []
+  const repeatableFlags: Array<string> = []
+
+  for (const param of params) {
+    const metadata = flagMetadata(param)
+    const longName = `--${metadata.name}`
+    longFlags.push(longName)
+    if (metadata.takesValue) valueFlags.push(longName)
+    if (metadata.repeatable) repeatableFlags.push(longName)
+    for (const alias of metadata.aliases) aliases.set(`-${alias}`, longName)
+  }
+
+  return { longFlags, aliases, valueFlags, repeatableFlags }
+}
+
+const commandSurface = (command: CommandValue): FlagSurface => {
+  if (!("config" in command)) {
+    throw new Error(`Effect CLI did not expose flags for '${command.name}'`)
+  }
+  const config = command.config
+  if (
+    typeof config !== "object" ||
+    config === null ||
+    !("flags" in config) ||
+    !Array.isArray(config.flags)
+  ) {
+    throw new Error(`Effect CLI did not expose flags for '${command.name}'`)
+  }
+
+  return flagSurface(config.flags)
+}
+
+const globalSurface = (): GlobalFlagSurface => {
+  const builtIns: unknown = GlobalFlag.BuiltIns
+  if (!Array.isArray(builtIns)) {
+    throw new Error("Effect CLI did not expose its built-in global flags")
+  }
+
+  const actionFlags = new Set<string>()
+  const flags = builtIns.map((builtIn) => {
+    if (
+      (typeof builtIn !== "object" && typeof builtIn !== "function") ||
+      builtIn === null ||
+      !("flag" in builtIn) ||
+      !("_tag" in builtIn) ||
+      typeof builtIn._tag !== "string"
+    ) {
+      throw new Error("Effect CLI exposed an unsupported built-in global flag")
+    }
+    if (builtIn._tag === "Action") {
+      // Only a presence-based action is idempotent. `--completions` is an action
+      // that takes a value, and Effect 4 would silently keep the first one, which
+      // is exactly what the duplicate rule exists to refuse.
+      const metadata = flagMetadata(builtIn.flag)
+      if (!metadata.takesValue) actionFlags.add(`--${metadata.name}`)
+    }
+    return builtIn.flag
+  })
+  return { ...flagSurface(flags), actionFlags }
+}
+
+const COMMANDS: ReadonlyArray<CommandValue> = [
+  syncCommand,
+  updateCommand,
+  modelCommand,
+  toolchainCommand,
+  modelsCommand,
+  statusCommand,
+  pluginsCommand,
+  skillsCommand,
+  docsCommand
+]
+
+// A Map, not a plain object: an object literal answers `toString` and friends from
+// `Object.prototype`, so an unknown subcommand with such a name would slip past the
+// unknown-command guard and dereference a surface that was never built.
+const COMMAND_SURFACES: ReadonlyMap<string, FlagSurface> = new Map(
+  COMMANDS.map((command) => [command.name, commandSurface(command)])
+)
+
+const GLOBAL_SURFACE: GlobalFlagSurface = globalSurface()
+
+const LEGACY_HINTS: Readonly<Record<string, string>> = {
+  "--force": "--force was renamed to --reconcile",
+  "--remove-plugins":
+    "--remove-plugins was renamed to --prune (it also removes marketplaces + kit-managed skills)",
+  "--680k": "--680k was renamed to --claude-compact-window=680k",
+  "--permissive": "--permissive was renamed to --claude-permissive",
+  "--supabase": "--supabase was renamed to --claude-plugin=supabase",
+  "--n8n": "--n8n was renamed to --claude-plugin=n8n",
+  "--skip-rtk": "--skip-rtk was renamed to --skip-bubblewrap",
+  "--claude": "--claude was renamed: pass the target as a word, e.g. 'sync claude'",
+  "--codex": "--codex was renamed: pass the target as a word, e.g. 'sync codex'",
+  "--agents": "--agents was renamed: pass the target as a word, e.g. 'sync agents'"
+}
+
+const flagNameOf = (token: string): string => {
+  const equals = token.indexOf("=")
+  return equals === -1 ? token : token.slice(0, equals)
+}
+
+const canonicalFlagName = (
+  name: string,
+  surface: FlagSurface | undefined
+): string | undefined => {
+  if (surface === undefined) return undefined
+  const aliased = surface.aliases.get(name)
+  if (aliased !== undefined) return aliased
+  return surface.longFlags.includes(name) ? name : undefined
+}
+
+const declaredFlagName = (
+  name: string,
+  commandSurface: FlagSurface | undefined
+): string | undefined =>
+  canonicalFlagName(name, commandSurface) ?? canonicalFlagName(name, GLOBAL_SURFACE)
+
+const declaredInAnySurface = (name: string): boolean => {
+  if (canonicalFlagName(name, GLOBAL_SURFACE) !== undefined) return true
+  return COMMANDS.some(
+    (command) => canonicalFlagName(name, COMMAND_SURFACES.get(command.name)) !== undefined
+  )
+}
+
+const takesValueInAnySurface = (name: string): boolean => {
+  const globalName = canonicalFlagName(name, GLOBAL_SURFACE)
+  if (globalName !== undefined && GLOBAL_SURFACE.valueFlags.includes(globalName)) return true
+  return COMMANDS.some((command) => {
+    const surface = COMMAND_SURFACES.get(command.name)
+    if (surface === undefined) return false
+    const canonicalName = canonicalFlagName(name, surface)
+    return canonicalName !== undefined && surface.valueFlags.includes(canonicalName)
+  })
+}
+
+/** The resolved subcommand word, or undefined at the root. */
+export const subcommandName = (args: ReadonlyArray<string>): string | undefined => {
+  for (let index = 0; index < args.length; index++) {
+    const token = args[index]
+    if (token === "--") return undefined
+    const name = flagNameOf(token)
+    if (token === name && takesValueInAnySurface(name)) {
+      const next = args[index + 1]
+      if (next === "--") return undefined
+      if (
+        next !== undefined &&
+        !(next.startsWith("-") && declaredInAnySurface(flagNameOf(next)))
+      ) {
+        index++
+        continue
+      }
+    }
+    if (!token.startsWith("-")) return token
+  }
+  return undefined
+}
+
+interface ScannedFlag {
+  readonly token: string
+  readonly name: string
+  readonly canonicalName: string | undefined
+  readonly hasValue: boolean
+  readonly takesValue: boolean
+}
+
+interface ArgvNormalization {
+  readonly flagIndex: number
+  readonly valueIndex: number
+  readonly token: string
+}
+
+interface ScannedArgv {
+  readonly flags: ReadonlyArray<ScannedFlag>
+  readonly normalizations: ReadonlyArray<ArgvNormalization>
+}
+
+const scanArgv = (
+  args: ReadonlyArray<string>,
+  commandSurface: FlagSurface | undefined
+): ScannedArgv => {
+  const flags: Array<ScannedFlag> = []
+  const normalizations: Array<ArgvNormalization> = []
+
+  for (let index = 0; index < args.length; index++) {
+    const token = args[index]
+    if (token === "--") break
+    if (!token.startsWith("-")) continue
+
+    const name = flagNameOf(token)
+    const canonicalName = declaredFlagName(name, commandSurface)
+    let hasValue = token.includes("=")
+    const takesValue =
+      canonicalName !== undefined &&
+      (commandSurface?.valueFlags.includes(canonicalName) === true ||
+        GLOBAL_SURFACE.valueFlags.includes(canonicalName))
+
+    if (!hasValue && takesValue) {
+      const next = args[index + 1]
+      const nextIsRecognizedFlag =
+        next !== undefined &&
+        next.startsWith("-") &&
+        declaredFlagName(flagNameOf(next), commandSurface) !== undefined
+      // A legitimate value may begin with `-`; only a recognized flag proves it is missing.
+      if (next !== undefined && next !== "--" && !nextIsRecognizedFlag) {
+        hasValue = true
+        if (next.startsWith("-")) {
+          // Effect 4's lexer treats any `-`-leading token as an option, so a legitimate
+          // dash-leading value only survives in the inline form.
+          normalizations.push({
+            flagIndex: index,
+            valueIndex: index + 1,
+            token: `${token}=${next}`
+          })
+        }
+        index++
+      }
+    }
+
+    flags.push({ token, name, canonicalName, hasValue, takesValue })
+  }
+
+  return { flags, normalizations }
+}
+
+const normalizeArgv = (
+  args: ReadonlyArray<string>,
+  normalizations: ReadonlyArray<ArgvNormalization>
+): ReadonlyArray<string> => {
+  if (normalizations.length === 0) return args
+
+  const normalized: Array<string> = []
+  let normalizationIndex = 0
+  for (let index = 0; index < args.length; index++) {
+    const normalization = normalizations[normalizationIndex]
+    if (normalization !== undefined && normalization.flagIndex === index) {
+      normalized.push(normalization.token)
+      index = normalization.valueIndex
+      normalizationIndex++
+      continue
+    }
+    normalized.push(args[index])
+  }
+  return normalized
+}
+
+const reject = (message: string): ArgvOutcome => ({
+  kind: "reject",
+  message,
+  exitCode: 2
+})
+
+const modelCatalogHint = (tool: Tool): string => {
+  const catalog = modelCatalog(tool)
+  const list = catalog.models
+    .map((model) => `  ${model.id}${model.note !== undefined ? `  — ${model.note}` : ""}`)
+    .join("\n")
+  return `Available ${tool} models (kit-verified ${catalog.verified} — SoT/models.json):\n${list}`
+}
+
+const missingModifierValue = (flag: string): string | undefined => {
+  switch (flag) {
+    case "--claude-model":
+    case "--codex-model": {
+      const tool: Tool = flag === "--claude-model" ? "claude" : "codex"
+      return `${modelCatalogHint(tool)}\n${flag} requires a value: ${flag}=<model>`
+    }
+    case "--claude-effort":
+    case "--codex-effort": {
+      const tool: Tool = flag === "--claude-effort" ? "claude" : "codex"
+      return `${effortCatalog(tool)}\n${flag} requires a value: ${effortFlagGrammar(tool)}`
+    }
+    case "--claude-advisor":
+      return `${advisorCatalog()}\n${flag} requires a value: ${advisorFlagGrammar()}`
+    case "--claude-compact-window":
+      return `${flag} requires a value: ${flag}=<tokens> (e.g. 680k)`
+    case "--claude-plugin":
+      return `${flag} requires a value: ${flag}=<${KNOWN_CLAUDE_OPTIN_PLUGINS.join("|")}>`
+    default:
+      return undefined
+  }
+}
+
+/** Validate the argument list, then hand back the arguments Effect 4 should parse. */
+export const prepareArgv = (args: ReadonlyArray<string>): ArgvOutcome => {
+  const subcommand = subcommandName(args)
+  const commandSurface = subcommand === undefined ? undefined : COMMAND_SURFACES.get(subcommand)
+  const { flags, normalizations } = scanArgv(args, commandSurface)
+  const unknownCommandWouldMisdiagnoseFlag =
+    subcommand !== undefined &&
+    commandSurface === undefined &&
+    flags.some((flag) => flag.canonicalName === undefined)
+  if (unknownCommandWouldMisdiagnoseFlag) {
+    return reject(`unknown command '${subcommand}'`)
+  }
+
+  if (subcommand === "sync") {
+    for (const flag of flags) {
+      const hint = LEGACY_HINTS[flag.name]
+      if (hint !== undefined) return reject(hint)
+    }
+  }
+
+  // Effect 4 expands clustered shorts, but the kit declares no clusterable alias
+  // pair, so refusing a cluster as one unknown flag is the conservative direction.
+  for (const flag of flags) {
+    if (flag.canonicalName !== undefined) continue
+    const scope = subcommand === undefined ? "" : ` for '${subcommand}'`
+    return reject(`unknown flag ${flag.token}${scope}`)
+  }
+
+  for (const flag of flags) {
+    if (!flag.token.includes("=") || flag.takesValue) continue
+    // These booleans are presence-based; Effect 4 would otherwise let
+    // `--dry-run=false` read as a dry run while performing a real mutating sync.
+    return reject(`flag ${flag.name} does not take a value`)
+  }
+
+  const seen = new Set<string>()
+  for (const flag of flags) {
+    const name = flag.canonicalName
+    if (name === undefined) continue
+    const duplicateAllowed =
+      commandSurface?.repeatableFlags.includes(name) === true ||
+      GLOBAL_SURFACE.repeatableFlags.includes(name) ||
+      GLOBAL_SURFACE.actionFlags.has(name)
+    if (!duplicateAllowed && seen.has(name)) {
+      return reject(`flag ${name} was given more than once`)
+    }
+    seen.add(name)
+  }
+
+  if (subcommand === "sync") {
+    for (const flag of flags) {
+      if (flag.hasValue) continue
+      const message = missingModifierValue(flag.name)
+      if (message !== undefined) return reject(message)
+    }
+  }
+
+  return { kind: "accept", args: normalizeArgv(args, normalizations) }
+}

package/cli/src/commands/docs.ts

@@ -1,4 +1,4 @@
-import { Args, Command, Options } from "@effect/cli"
+import { Argument, Command, Flag } from "effect/unstable/cli"
 import { Console, Effect, Option } from "effect"
 import { bail } from "../engine"
 import overview from "../../docs/overview.md" with { type: "text" }
@@ -23,12 +23,12 @@ const TOPICS: Record<string, { summary: string; body: string }> = {
   "platforms": { summary: "Platform support: Linux/macOS x64 and arm64", body: platforms }
 }
 
-const topic = Args.text({ name: "topic" }).pipe(
-  Args.withDescription(`One of: ${Object.keys(TOPICS).join(", ")}`),
-  Args.optional
+const topic = Argument.string("topic").pipe(
+  Argument.withDescription(`One of: ${Object.keys(TOPICS).join(", ")}`),
+  Argument.optional
 )
-const json = Options.boolean("json").pipe(
-  Options.withDescription("List topics as JSON")
+const json = Flag.boolean("json").pipe(
+  Flag.withDescription("List topics as JSON")
 )
 
 export const docsCommand = Command.make("docs", { topic, json }, (config) =>

package/cli/src/commands/model.ts

@@ -1,21 +1,21 @@
-import { Args, Command, Options, Prompt } from "@effect/cli"
+import { Argument, Command, Flag, Prompt } from "effect/unstable/cli"
 import { Effect, Option } from "effect"
 import { bail, engine } from "../engine"
 import { modelCatalog, type Tool } from "../manifests"
 
-const tool = Args.text({ name: "tool" }).pipe(
-  Args.withDescription("Which tool: claude | codex")
+const tool = Argument.string("tool").pipe(
+  Argument.withDescription("Which tool: claude | codex")
 )
-const value = Args.text({ name: "value" }).pipe(
-  Args.withDescription("Model to set (omit to view current + pick interactively on a TTY)"),
-  Args.optional
+const value = Argument.string("value").pipe(
+  Argument.withDescription("Model to set (omit to view current + pick interactively on a TTY)"),
+  Argument.optional
 )
-const dryRun = Options.boolean("dry-run").pipe(
-  Options.withDescription("Preview without applying")
+const dryRun = Flag.boolean("dry-run").pipe(
+  Flag.withDescription("Preview without applying")
 )
-const verbose = Options.boolean("verbose").pipe(
-  Options.withAlias("v"),
-  Options.withDescription("Also print no-op confirmations (already in sync, up to date)")
+const verbose = Flag.boolean("verbose").pipe(
+  Flag.withAlias("v"),
+  Flag.withDescription("Also print no-op confirmations (already in sync, up to date)")
 )
 
 const KEEP = "__keep__"

package/cli/src/commands/models.ts

@@ -1,14 +1,14 @@
-import { Args, Command, Options } from "@effect/cli"
+import { Argument, Command, Flag } from "effect/unstable/cli"
 import { Console, Effect, Option } from "effect"
 import { bail } from "../engine"
 import { modelCatalog, type Tool } from "../manifests"
 
-const tool = Args.text({ name: "tool" }).pipe(
-  Args.withDescription("claude | codex (omit for both tool catalogs)"),
-  Args.optional
+const tool = Argument.string("tool").pipe(
+  Argument.withDescription("claude | codex (omit for both tool catalogs)"),
+  Argument.optional
 )
-const json = Options.boolean("json").pipe(
-  Options.withDescription("Machine-readable output")
+const json = Flag.boolean("json").pipe(
+  Flag.withDescription("Machine-readable output")
 )
 
 const renderTool = (t: Tool) =>

package/cli/src/commands/plugins.ts

@@ -1,14 +1,14 @@
-import { Args, Command, Options } from "@effect/cli"
+import { Argument, Command, Flag } from "effect/unstable/cli"
 import { Console, Effect, Option } from "effect"
 import { bail } from "../engine"
 import { pluginsView } from "../manifests"
 
-const action = Args.text({ name: "action" }).pipe(
-  Args.withDescription("list (default)"),
-  Args.optional
+const action = Argument.string("action").pipe(
+  Argument.withDescription("list (default)"),
+  Argument.optional
 )
-const json = Options.boolean("json").pipe(
-  Options.withDescription("Machine-readable output")
+const json = Flag.boolean("json").pipe(
+  Flag.withDescription("Machine-readable output")
 )
 
 export const pluginsCommand = Command.make("plugins", { action, json }, (config) =>

package/cli/src/commands/skills.ts

@@ -1,14 +1,14 @@
-import { Args, Command, Options } from "@effect/cli"
+import { Argument, Command, Flag } from "effect/unstable/cli"
 import { Console, Effect, Option } from "effect"
 import { bail } from "../engine"
 import { skillsView } from "../manifests"
 
-const action = Args.text({ name: "action" }).pipe(
-  Args.withDescription("list (default)"),
-  Args.optional
+const action = Argument.string("action").pipe(
+  Argument.withDescription("list (default)"),
+  Argument.optional
 )
-const json = Options.boolean("json").pipe(
-  Options.withDescription("Machine-readable output")
+const json = Flag.boolean("json").pipe(
+  Flag.withDescription("Machine-readable output")
 )
 
 export const skillsCommand = Command.make("skills", { action, json }, (config) =>

package/cli/src/commands/status.ts

@@ -1,4 +1,4 @@
-import { Command, Options } from "@effect/cli"
+import { Command, Flag } from "effect/unstable/cli"
 import { Console, Effect } from "effect"
 import { engineCapture } from "../engine"
 import {
@@ -11,8 +11,8 @@ import {
 } from "../manifests"
 import { kitHome } from "../kitHome"
 
-const json = Options.boolean("json").pipe(
-  Options.withDescription("Machine-readable output")
+const json = Flag.boolean("json").pipe(
+  Flag.withDescription("Machine-readable output")
 )
 
 interface Drift {

package/cli/src/commands/sync.ts

@@ -1,18 +1,11 @@
-import { Args, Command, Options } from "@effect/cli"
+import { Argument, Command, Flag } from "effect/unstable/cli"
 import { Effect, Option } from "effect"
 import { spawnSync } from "node:child_process"
 import { existsSync } from "node:fs"
 import { join } from "node:path"
 import { bail, engine } from "../engine"
 import type { Logger } from "../engine-native/logger"
-import {
-  advisorCatalog,
-  advisorFlagGrammar,
-  effortCatalog,
-  effortFlagGrammar
-} from "../efforts"
 import { kitHome } from "../kitHome"
-import { modelCatalog, type Tool } from "../manifests"
 import { LoggerService } from "../services"
 
 /** Best-effort update autodetection: nudge (never block, never fail) when
@@ -38,90 +31,66 @@ const updateNudge = (logger: Logger): void => {
 
 const VALID_TARGETS = ["claude", "codex", "agents"]
 
-// Renamed pre-CLI flags: @effect/cli routes unknown flags into the excess
-// positional args, so the rename hints are mirrored here before EngineNative
-// sees the normalized argv.
-const LEGACY_HINTS: Record<string, string> = {
-  "--force": "--force was renamed to --reconcile",
-  "--remove-plugins":
-    "--remove-plugins was renamed to --prune (it also removes marketplaces + kit-managed skills)",
-  "--680k": "--680k was renamed to --claude-compact-window=680k",
-  "--permissive": "--permissive was renamed to --claude-permissive",
-  "--supabase": "--supabase was renamed to --claude-plugin=supabase",
-  "--n8n": "--n8n was renamed to --claude-plugin=n8n",
-  "--skip-rtk": "--skip-rtk was renamed to --skip-bubblewrap",
-  "--claude": "--claude was renamed: pass the target as a word, e.g. 'sync claude'",
-  "--codex": "--codex was renamed: pass the target as a word, e.g. 'sync codex'",
-  "--agents": "--agents was renamed: pass the target as a word, e.g. 'sync agents'"
-}
-
-const modelCatalogHint = (t: Tool): string => {
-  const c = modelCatalog(t)
-  const list = c.models
-    .map((m) => `  ${m.id}${m.note !== undefined ? `  — ${m.note}` : ""}`)
-    .join("\n")
-  return `Available ${t} models (kit-verified ${c.verified} — SoT/models.json):\n${list}`
-}
-
-const targets = Args.text({ name: "target" }).pipe(
-  Args.withDescription("Sync targets: claude, codex, agents (default: all three)"),
-  Args.repeated
+const targets = Argument.variadic(
+  Argument.string("target").pipe(
+    Argument.withDescription("Sync targets: claude, codex, agents (default: all three)")
+  )
 )
 
-const dryRun = Options.boolean("dry-run").pipe(
-  Options.withDescription("Preview without applying")
+const dryRun = Flag.boolean("dry-run").pipe(
+  Flag.withDescription("Preview without applying")
 )
-const reconcile = Options.boolean("reconcile").pipe(
-  Options.withDescription("Reconcile kit-owned settings with SoT (SoT keys win; user-only keys preserved; permissions arrays replaced)")
+const reconcile = Flag.boolean("reconcile").pipe(
+  Flag.withDescription("Reconcile kit-owned settings with SoT (SoT keys win; user-only keys preserved; permissions arrays replaced)")
 )
-const prune = Options.boolean("prune").pipe(
-  Options.withDescription("Uninstall kit-managed installs not in SoT (plugins, marketplaces, universal skills)")
+const prune = Flag.boolean("prune").pipe(
+  Flag.withDescription("Uninstall kit-managed installs not in SoT (plugins, marketplaces, universal skills)")
 )
-const skipBubblewrap = Options.boolean("skip-bubblewrap").pipe(
-  Options.withDescription("Skip optional bubblewrap bootstrap (Codex Linux sandbox)")
+const skipBubblewrap = Flag.boolean("skip-bubblewrap").pipe(
+  Flag.withDescription("Skip optional bubblewrap bootstrap (Codex Linux sandbox)")
 )
-const skipPluginRefresh = Options.boolean("skip-plugin-refresh").pipe(
-  Options.withDescription("Install missing plugins but skip refresh-only updates for existing plugins")
+const skipPluginRefresh = Flag.boolean("skip-plugin-refresh").pipe(
+  Flag.withDescription("Install missing plugins but skip refresh-only updates for existing plugins")
 )
-const yes = Options.boolean("yes").pipe(
-  Options.withDescription("Auto-accept toolchain prompts (containers/CI)")
+const yes = Flag.boolean("yes").pipe(
+  Flag.withDescription("Auto-accept toolchain prompts (containers/CI)")
 )
-const verbose = Options.boolean("verbose").pipe(
-  Options.withAlias("v"),
-  Options.withDescription("Also print no-op confirmations (already in sync, up to date, left as-is)")
+const verbose = Flag.boolean("verbose").pipe(
+  Flag.withAlias("v"),
+  Flag.withDescription("Also print no-op confirmations (already in sync, up to date, left as-is)")
 )
-const claudeModel = Options.text("claude-model").pipe(
-  Options.withDescription("Deploy-time modifier: set deployed Claude model (see `docks-kit models claude`)"),
-  Options.optional
+const claudeModel = Flag.string("claude-model").pipe(
+  Flag.withDescription("Deploy-time modifier: set deployed Claude model (see `docks-kit models claude`)"),
+  Flag.optional
 )
-const claudeEffort = Options.text("claude-effort").pipe(
-  Options.withDescription("Deploy-time modifier: set Claude effortLevel (bare flag shows valid levels)"),
-  Options.optional
+const claudeEffort = Flag.string("claude-effort").pipe(
+  Flag.withDescription("Deploy-time modifier: set Claude effortLevel (bare flag shows valid levels)"),
+  Flag.optional
 )
-const claudeAdvisor = Options.text("claude-advisor").pipe(
-  Options.withDescription("Deploy-time modifier: set Claude advisor on/off/default"),
-  Options.optional
+const claudeAdvisor = Flag.string("claude-advisor").pipe(
+  Flag.withDescription("Deploy-time modifier: set Claude advisor on/off/default"),
+  Flag.optional
 )
-const claudeCompactWindow = Options.text("claude-compact-window").pipe(
-  Options.withDescription("Deploy-time modifier: set deployed autocompact window in tokens (e.g. 680000 or 680k)"),
-  Options.optional
+const claudeCompactWindow = Flag.string("claude-compact-window").pipe(
+  Flag.withDescription("Deploy-time modifier: set deployed autocompact window in tokens (e.g. 680000 or 680k)"),
+  Flag.optional
 )
-const claudePermissive = Options.boolean("claude-permissive").pipe(
-  Options.withDescription("Deploy-time modifier: empty permissions.ask/deny in deployed settings (sandboxes)")
+const claudePermissive = Flag.boolean("claude-permissive").pipe(
+  Flag.withDescription("Deploy-time modifier: empty permissions.ask/deny in deployed settings (sandboxes)")
 )
-const claudePlugin = Options.text("claude-plugin").pipe(
-  Options.withDescription(
+const claudePlugin = Flag.string("claude-plugin").pipe(
+  Flag.withDescription(
     "Sticky opt-in plugin(s); repeatable and/or comma-separated (known: supabase, n8n)"
   ),
-  Options.repeated
+  Flag.atLeast(0)
 )
-const codexModel = Options.text("codex-model").pipe(
-  Options.withDescription("Deploy-time modifier: set deployed Codex model (see `docks-kit models codex`)"),
-  Options.optional
+const codexModel = Flag.string("codex-model").pipe(
+  Flag.withDescription("Deploy-time modifier: set deployed Codex model (see `docks-kit models codex`)"),
+  Flag.optional
 )
-const codexEffort = Options.text("codex-effort").pipe(
-  Options.withDescription("Deploy-time modifier: set Codex model_reasoning_effort (bare flag shows valid levels)"),
-  Options.optional
+const codexEffort = Flag.string("codex-effort").pipe(
+  Flag.withDescription("Deploy-time modifier: set Codex model_reasoning_effort (bare flag shows valid levels)"),
+  Flag.optional
 )
 
 export const syncCommand = Command.make(
@@ -146,24 +115,6 @@ export const syncCommand = Command.make(
   },
   (config) =>
     Effect.gen(function* () {
-      for (const t of config.targets) {
-        if (VALID_TARGETS.includes(t)) continue
-        if (t === "--claude-model" || t === "--codex-model") {
-          const tool: Tool = t === "--claude-model" ? "claude" : "codex"
-          return yield* bail(`${modelCatalogHint(tool)}\n${t} requires a value: ${t}=<model>`)
-        }
-        if (t === "--claude-effort" || t === "--codex-effort") {
-          const tool: Tool = t === "--claude-effort" ? "claude" : "codex"
-          return yield* bail(`${effortCatalog(tool)}\n${t} requires a value: ${effortFlagGrammar(tool)}`)
-        }
-        if (t === "--claude-advisor") {
-          return yield* bail(`${advisorCatalog()}\n${t} requires a value: ${advisorFlagGrammar()}`)
-        }
-        const hint = LEGACY_HINTS[t]
-        if (hint !== undefined) {
-          return yield* bail(hint)
-        }
-      }
       const bad = config.targets.filter((t) => !VALID_TARGETS.includes(t))
       if (bad.length > 0) {
         return yield* bail(

package/cli/src/commands/toolchain.ts

@@ -1,23 +1,23 @@
-import { Args, Command, Options } from "@effect/cli"
+import { Argument, Command, Flag } from "effect/unstable/cli"
 import { Effect, Option } from "effect"
 import { bail, engine } from "../engine"
 
 const MANAGED = ["bun", "effect-solutions"]
 
-const op = Args.text({ name: "op" }).pipe(
-  Args.withDescription("check (default) | ensure <tool>"),
-  Args.optional
+const op = Argument.string("op").pipe(
+  Argument.withDescription("check (default) | ensure <tool>"),
+  Argument.optional
 )
-const tool = Args.text({ name: "tool" }).pipe(
-  Args.withDescription(`Managed tool for ensure: ${MANAGED.join(", ")}`),
-  Args.optional
+const tool = Argument.string("tool").pipe(
+  Argument.withDescription(`Managed tool for ensure: ${MANAGED.join(", ")}`),
+  Argument.optional
 )
-const yes = Options.boolean("yes").pipe(
-  Options.withDescription("Auto-accept above-verified installs")
+const yes = Flag.boolean("yes").pipe(
+  Flag.withDescription("Auto-accept above-verified installs")
 )
-const verbose = Options.boolean("verbose").pipe(
-  Options.withAlias("v"),
-  Options.withDescription("Also print no-op confirmations (present, up to date)")
+const verbose = Flag.boolean("verbose").pipe(
+  Flag.withAlias("v"),
+  Flag.withDescription("Also print no-op confirmations (present, up to date)")
 )
 
 export const toolchainCommand = Command.make("toolchain", { op, tool, yes, verbose }, (config) =>

package/cli/src/commands/update.ts

@@ -1,4 +1,4 @@
-import { Command, Options } from "@effect/cli"
+import { Command, Flag } from "effect/unstable/cli"
 import { Console, Effect } from "effect"
 import { spawnSync } from "node:child_process"
 import { existsSync, readFileSync } from "node:fs"
@@ -6,8 +6,8 @@ import { join } from "node:path"
 import { bail, compiled } from "../engine"
 import { kitHome } from "../kitHome"
 
-const noSync = Options.boolean("no-sync").pipe(
-  Options.withDescription("Update the kit only; skip the chained flag-less sync")
+const noSync = Flag.boolean("no-sync").pipe(
+  Flag.withDescription("Update the kit only; skip the chained flag-less sync")
 )
 
 const git = (home: string, args: Array<string>): { ok: boolean; out: string } => {

package/cli/src/engine-native/parseArgs.ts

@@ -23,7 +23,7 @@ export class ExitError extends Error {
   }
 }
 
-const KNOWN_CLAUDE_OPTIN_PLUGINS = ["supabase", "n8n"]
+export const KNOWN_CLAUDE_OPTIN_PLUGINS = ["supabase", "n8n"]
 const MODIFIER_FLAGS = new Set<ModifierFlag>([
   "--claude-model",
   "--claude-effort",

package/cli/src/engine.ts

@@ -7,7 +7,7 @@ import { DependencyManagerService, LoggerService, PlatformService } from "./serv
 
 /**
  * The single seam between the typed CLI and EngineNative. Engine execution
- * stays in-process after @effect/cli has parsed pickers and flag spellings.
+ * stays in-process after effect/unstable/cli has parsed pickers and flag spellings.
  */
 const bashRemovedMessage = "bash engine removed — recover at tag bash-engine-final"
 const bashEngineRequested = (): boolean => process.env["DOCKS_KIT_ENGINE"] === "bash"

package/cli/src/generated/sotPayload.ts

@@ -1,7 +1,7 @@
 // Generated by cli/scripts/generate-sot-payload.ts. DO NOT EDIT.
 // Edit SoT/, notification.mp3, or package.json, then run: bun cli/scripts/generate-sot-payload.ts
 
-export const GENERATED_PACKAGE_VERSION = "0.14.4"
+export const GENERATED_PACKAGE_VERSION = "0.15.0"
 
 export const GENERATED_PAYLOAD_TEXT = {
   "SoT/.agents/skills.txt": "# Universal AI-agent skill manifest intentionally empty.\n# Global skill discovery is opt-in: add one <owner>/<repo> slug per line.\n# EngineNative ignores comments and blank lines.\n",

package/cli/src/main.ts

@@ -1,8 +1,7 @@
 #!/usr/bin/env bun
-import { Command } from "@effect/cli"
-import { BunContext, BunRuntime } from "@effect/platform-bun"
+import { Command, CliOutput } from "effect/unstable/cli"
+import { BunRuntime, BunServices } from "@effect/platform-bun"
 import { Console, Effect, Layer } from "effect"
-import { engine } from "./engine"
 import { EngineServicesLive } from "./services"
 import { docsCommand } from "./commands/docs"
 import { modelCommand } from "./commands/model"
@@ -14,6 +13,7 @@ import { syncCommand } from "./commands/sync"
 import { toolchainCommand } from "./commands/toolchain"
 import { updateCommand } from "./commands/update"
 import { GENERATED_PACKAGE_VERSION } from "./generated/sotPayload"
+import { prepareArgv } from "./argv"
 
 
 const root = Command.make("docks-kit", {}, () =>
@@ -50,8 +50,16 @@ const root = Command.make("docks-kit", {}, () =>
   ])
 )
 
+// v4's default formatter renders `name vversion`, but the `docks-kit` launcher
+// compares `--version` against the bare `package.json` version. The trailing
+// newline reproduces the characterized byte-for-byte output of the v3 CLI.
+const bareVersionFormatter: CliOutput.Formatter = {
+  ...CliOutput.defaultFormatter(),
+  formatVersion: (_name, version) => `${version}\n`
+}
+
 // Harness-private raw channel:
-// `DOCKS_KIT_ENGINE=native-raw` bypasses @effect/cli and hands the raw engine
+// `DOCKS_KIT_ENGINE=native-raw` bypasses effect/unstable/cli and hands the raw engine
 // argv to EngineNative so golden tests drive the internal vocabulary directly.
 // PUBLIC engine execution lives at the engine.ts seam after the CLI has
 // parsed/normalized pickers, --flag value forms, and non-engine commands.
@@ -60,27 +68,18 @@ if (process.env["DOCKS_KIT_ENGINE"] === "native-raw") {
   process.exit(await runEngineNative(process.argv.slice(2)))
 }
 
-const cli = Command.run(root, {
-  name: "docks-kit",
-  version: GENERATED_PACKAGE_VERSION
-})
-
-// Normalize the repeatable plugin's documented equals form and exact empty
-// text-option assignments that @effect/cli otherwise routes into positional
-// targets. EngineNative owns the resulting shared empty-value validation.
-const emptyTextOptions = new Set([
-  "--claude-model=",
-  "--claude-effort=",
-  "--claude-advisor=",
-  "--codex-model=",
-  "--codex-effort=",
-])
-const argv = process.argv.flatMap((a, index, all) => {
-  if (a.startsWith("--claude-plugin=")) {
-    return ["--claude-plugin", a.slice("--claude-plugin=".length)]
-  }
-  if (emptyTextOptions.has(a)) return [a.slice(0, -1), ""]
-  return [a]
-})
+// Validate and normalize before parsing because the kit refuses to guess at unrecognized
+// or duplicated flags, and Effect 4 would otherwise negate `--no-<flag>` into a real
+// mutating run. This seam owns argument normalization.
+const prepared = prepareArgv(process.argv.slice(2))
+if (prepared.kind === "reject") {
+  process.stderr.write(`${prepared.message}\n`)
+  process.exit(prepared.exitCode)
+}
 
-cli(argv).pipe(Effect.provide(Layer.mergeAll(BunContext.layer, EngineServicesLive)), BunRuntime.runMain)
+Command.runWith(root, { version: GENERATED_PACKAGE_VERSION })(prepared.args).pipe(
+  Effect.provide(
+    Layer.mergeAll(BunServices.layer, EngineServicesLive, CliOutput.layer(bareVersionFormatter))
+  ),
+  BunRuntime.runMain
+)

package/cli/src/services.ts

@@ -8,14 +8,14 @@ import { Context, Layer } from "effect"
 import { makeLogger, type Logger, type LoggerSinks } from "./engine-native/logger"
 import { makeEngineServices, makePlatform, type DependencyManager, type Platform } from "./engine-native/services"
 
-export class LoggerService extends Context.Tag("docks-kit/Logger")<LoggerService, Logger>() {}
+export class LoggerService extends Context.Service<LoggerService, Logger>()("docks-kit/Logger") {}
 
-export class DependencyManagerService extends Context.Tag("docks-kit/DependencyManager")<
+export class DependencyManagerService extends Context.Service<
   DependencyManagerService,
   DependencyManager
->() {}
+>()("docks-kit/DependencyManager") {}
 
-export class PlatformService extends Context.Tag("docks-kit/Platform")<PlatformService, Platform>() {}
+export class PlatformService extends Context.Service<PlatformService, Platform>()("docks-kit/Platform") {}
 
 const live = makeEngineServices()
 

package/docks-kit

@@ -69,7 +69,7 @@ fi
 
 # Sentinel is a real dependency dir, not bare node_modules/ — a failed or
 # partial install leaves node_modules/ present and would suppress the repair.
-if [[ ! -d "$REPO_DIR/node_modules/@effect/cli" ]]; then
+if [[ ! -d "$REPO_DIR/node_modules/effect" ]]; then
   echo "[docks-kit] Installing CLI dependencies (bun install --frozen-lockfile)..." >&2
   (cd "$REPO_DIR" && "$BUN" install --frozen-lockfile >/dev/null)
 fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docks-kit",
-  "version": "0.14.4",
+  "version": "0.15.0",
   "description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Claude Code, Codex, and universal agent skills",
   "type": "module",
   "license": "MIT",
@@ -35,15 +35,13 @@
     "test:ci": "bun run check:generated && bun run typecheck && bun run test:unit && bun run test:runtime:posix && bun run golden:dryrun && bun run golden:mutation"
   },
   "dependencies": {
-    "@effect/cli": "0.75.2",
-    "@effect/platform": "0.96.1",
-    "@effect/platform-bun": "0.90.0",
-    "effect": "3.21.4"
+    "@effect/platform-bun": "4.0.0-beta.107",
+    "effect": "4.0.0-beta.107"
   },
   "devDependencies": {
-    "@effect/vitest": "0.29.0",
+    "@effect/vitest": "4.0.0-beta.107",
     "@types/bun": "^1.3.0",
     "typescript": "7.0.2",
-    "vitest": "3.2.7"
+    "vitest": "4.1.10"
   }
 }