docks-kit 0.17.1 → 0.17.2

package/cli/src/argvSurface.ts

@@ -0,0 +1,371 @@
+/**
+ * Flag grammar and parsing for the Effect CLI layer: flag surfaces derived
+ * from caller-supplied command values, argv scanning/normalization,
+ * subcommand detection, and the omp passthrough boundary. Pure: surfaces are
+ * built from structural command values, so this module never touches Effect
+ * CLI globals or process state.
+ */
+
+export interface FlagSurface {
+  readonly longFlags: ReadonlyArray<string>;
+  readonly aliases: ReadonlyMap<string, string>;
+  readonly valueFlags: ReadonlyArray<string>;
+  readonly repeatableFlags: ReadonlyArray<string>;
+}
+
+export interface GlobalFlagSurface extends FlagSurface {
+  readonly actionFlags: ReadonlySet<string>;
+}
+
+export interface CommandValue {
+  readonly name: string;
+}
+
+export interface ArgvSurfaces {
+  readonly commandSurfaces: ReadonlyMap<string, FlagSurface>;
+  readonly globalSurface: GlobalFlagSurface;
+}
+
+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 buildCommandSurface = (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 = (builtIns: unknown): GlobalFlagSurface => {
+  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 };
+};
+
+export const buildSurfaces = (
+  commands: ReadonlyArray<CommandValue>,
+  builtIns: unknown,
+): ArgvSurfaces => {
+  // 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 commandSurfaces: ReadonlyMap<string, FlagSurface> = new Map(
+    commands.map((command) => [command.name, buildCommandSurface(command)]),
+  );
+  return { commandSurfaces, globalSurface: globalSurface(builtIns) };
+};
+
+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,
+  surfaces: ArgvSurfaces,
+): string | undefined =>
+  canonicalFlagName(name, commandSurface) ?? canonicalFlagName(name, surfaces.globalSurface);
+
+const declaredInAnySurface = (name: string, surfaces: ArgvSurfaces): boolean => {
+  if (canonicalFlagName(name, surfaces.globalSurface) !== undefined) return true;
+  for (const surface of surfaces.commandSurfaces.values()) {
+    if (canonicalFlagName(name, surface) !== undefined) return true;
+  }
+  return false;
+};
+
+const takesValueInAnySurface = (name: string, surfaces: ArgvSurfaces): boolean => {
+  const globalName = canonicalFlagName(name, surfaces.globalSurface);
+  if (globalName !== undefined && surfaces.globalSurface.valueFlags.includes(globalName))
+    return true;
+  for (const surface of surfaces.commandSurfaces.values()) {
+    const canonicalName = canonicalFlagName(name, surface);
+    if (canonicalName !== undefined && surface.valueFlags.includes(canonicalName)) return true;
+  }
+  return false;
+};
+
+/** The resolved subcommand word, or undefined at the root. */
+export const subcommandName = (
+  args: ReadonlyArray<string>,
+  surfaces: ArgvSurfaces,
+): 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, surfaces)) {
+      const next = args[index + 1];
+      if (next === "--") return undefined;
+      if (
+        next !== undefined &&
+        !(next.startsWith("-") && declaredInAnySurface(flagNameOf(next), surfaces))
+      ) {
+        index++;
+        continue;
+      }
+    }
+    if (!token.startsWith("-")) return token;
+  }
+  return undefined;
+};
+
+export interface ScannedFlag {
+  readonly token: string;
+  readonly name: string;
+  readonly canonicalName: string | undefined;
+  readonly hasValue: boolean;
+  readonly takesValue: boolean;
+}
+
+export interface ArgvNormalization {
+  readonly flagIndex: number;
+  readonly valueIndex: number;
+  readonly token: string;
+}
+
+export interface ScannedArgv {
+  readonly flags: ReadonlyArray<ScannedFlag>;
+  readonly normalizations: ReadonlyArray<ArgvNormalization>;
+}
+
+export const scanArgv = (
+  args: ReadonlyArray<string>,
+  commandSurface: FlagSurface | undefined,
+  surfaces: ArgvSurfaces,
+): 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, surfaces);
+    let hasValue = token.includes("=");
+    const takesValue =
+      canonicalName !== undefined &&
+      (commandSurface?.valueFlags.includes(canonicalName) === true ||
+        surfaces.globalSurface.valueFlags.includes(canonicalName));
+
+    if (!hasValue && takesValue) {
+      const next = args[index + 1];
+      const nextIsRecognizedFlag =
+        next !== undefined &&
+        next.startsWith("-") &&
+        declaredFlagName(flagNameOf(next), commandSurface, surfaces) !== 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 };
+};
+
+export 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;
+};
+
+// Without the injected `--`, Effect 4 rejects a forwarded flag such as `-p` or
+// `--mode` as unrecognized. The omp launcher therefore owns a passthrough
+// boundary: the first token after the `omp` word that is neither a flag
+// declared on the omp or global surface nor a value consumed by such a flag
+// starts the verbatim tail forwarded to omp. An undeclared long flag joins the
+// tail too, because most omp flags are long (`--mode`, `--continue`,
+// `--models`), and omp itself reports an unrecognized one accurately. Use
+// `docks-kit omp -- --model x` to reach omp's own same-named flag.
+export const spliceOmpBoundary = (
+  args: ReadonlyArray<string>,
+  surfaces: ArgvSurfaces,
+): ReadonlyArray<string> => {
+  const surface = surfaces.commandSurfaces.get("omp");
+  let ompIndex = -1;
+  for (let index = 0; index < args.length; index++) {
+    const token = args[index] as string;
+    if (token === "--") return args;
+    const name = flagNameOf(token);
+    if (token === name && takesValueInAnySurface(name, surfaces)) {
+      const next = args[index + 1];
+      if (next === "--") return args;
+      if (
+        next !== undefined &&
+        !(next.startsWith("-") && declaredInAnySurface(flagNameOf(next), surfaces))
+      ) {
+        index++;
+        continue;
+      }
+    }
+    if (!token.startsWith("-")) {
+      ompIndex = index;
+      break;
+    }
+  }
+  if (ompIndex === -1 || args[ompIndex] !== "omp") return args;
+  for (let index = ompIndex + 1; index < args.length; index++) {
+    const token = args[index] as string;
+    // An explicit delimiter already marks the tail; a second one would be
+    // forwarded to omp as a literal argument.
+    if (token === "--") return args;
+    if (!token.startsWith("-")) {
+      return [...args.slice(0, index), "--", ...args.slice(index)];
+    }
+    const name = flagNameOf(token);
+    const canonical = declaredFlagName(name, surface, surfaces);
+    if (canonical === undefined) return [...args.slice(0, index), "--", ...args.slice(index)];
+    const takesValue =
+      surface?.valueFlags.includes(canonical) === true ||
+      surfaces.globalSurface.valueFlags.includes(canonical);
+    if (takesValue && !token.includes("=")) {
+      const next = args[index + 1];
+      if (
+        next !== undefined &&
+        !(
+          next.startsWith("-") &&
+          declaredFlagName(flagNameOf(next), surface, surfaces) !== undefined
+        )
+      ) {
+        index++;
+      }
+    }
+  }
+  return args;
+};

package/cli/src/argvValidate.ts

@@ -0,0 +1,122 @@
+/**
+ * Per-command validation for the Effect CLI layer: legacy-flag hints,
+ * unknown-command/flag detection, boolean-value and duplicate rejection, and
+ * the sync modifiers' missing-value diagnostics. Operates on scanned flags so
+ * the grammar machinery stays in argvSurface.ts.
+ */
+
+import { KNOWN_CLAUDE_OPTIN_PLUGINS } from "./engine-native/parseModifiers";
+import { modelCatalog } from "./engine-native/models";
+import { advisorCatalog, advisorFlagGrammar, effortCatalog, effortFlagGrammar } from "./efforts";
+import type { Tool } from "./manifests";
+import type { ArgvSurfaces, FlagSurface, ScannedFlag } from "./argvSurface";
+
+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 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;
+  }
+};
+
+/**
+ * Run the validation checks in diagnostic order. Returns the reject message
+ * for the first failure, or undefined when the scanned flags are valid.
+ */
+export const validateScannedArgv = (
+  subcommand: string | undefined,
+  commandSurface: FlagSurface | undefined,
+  surfaces: ArgvSurfaces,
+  flags: ReadonlyArray<ScannedFlag>,
+): string | undefined => {
+  const unknownCommandWouldMisdiagnoseFlag =
+    subcommand !== undefined &&
+    commandSurface === undefined &&
+    flags.some((flag) => flag.canonicalName === undefined);
+  if (unknownCommandWouldMisdiagnoseFlag) {
+    return `unknown command '${subcommand}'`;
+  }
+
+  if (subcommand === "sync") {
+    for (const flag of flags) {
+      const hint = LEGACY_HINTS[flag.name];
+      if (hint !== undefined) return 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 `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 `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 ||
+      surfaces.globalSurface.repeatableFlags.includes(name) ||
+      surfaces.globalSurface.actionFlags.has(name);
+    if (!duplicateAllowed && seen.has(name)) {
+      return `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 message;
+    }
+  }
+
+  return undefined;
+};

package/cli/src/commands/docs.ts

@@ -1,42 +1,57 @@
-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" }
-import flags from "../../docs/flags.md" with { type: "text" }
-import modifiers from "../../docs/modifiers.md" with { type: "text" }
-import models from "../../docs/models.md" with { type: "text" }
-import toolchain from "../../docs/toolchain.md" with { type: "text" }
-import plugins from "../../docs/plugins.md" with { type: "text" }
-import syncLayers from "../../docs/sync-layers.md" with { type: "text" }
-import install from "../../docs/install.md" with { type: "text" }
-import platforms from "../../docs/platforms.md" with { type: "text" }
-import ompModels from "../../docs/omp-models.md" with { type: "text" }
+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" };
+import flags from "../../docs/flags.md" with { type: "text" };
+import modifiers from "../../docs/modifiers.md" with { type: "text" };
+import models from "../../docs/models.md" with { type: "text" };
+import toolchain from "../../docs/toolchain.md" with { type: "text" };
+import plugins from "../../docs/plugins.md" with { type: "text" };
+import syncLayers from "../../docs/sync-layers.md" with { type: "text" };
+import install from "../../docs/install.md" with { type: "text" };
+import platforms from "../../docs/platforms.md" with { type: "text" };
+import ompModels from "../../docs/omp-models.md" with { type: "text" };
 
 const TOPICS: Record<string, { summary: string; body: string }> = {
-  "overview": { summary: "What docks-kit is and how the pieces fit", body: overview },
-  "sync-layers": { summary: "The three sync layers and additive-by-default semantics", body: syncLayers },
-  "flags": { summary: "Full flag reference incl. the old→new rename table", body: flags },
-  "modifiers": { summary: "Deploy-time modifiers and the flag-less-sync-reverts contract", body: modifiers },
-  "models": { summary: "Model catalog, validation rules, model get/set", body: models },
-  "toolchain": { summary: "Verified-version floors and the doctor table", body: toolchain },
-  "plugins": { summary: "enabledPlugins tri-state + optional plugin opt-ins", body: plugins },
-  "install": { summary: "Install paths: repo checkout, bun add -g, POSIX/Windows installers", body: install },
-  "platforms": { summary: "Platform support: Linux, macOS, and Windows on x64 and arm64", body: platforms },
-  "omp-models": { summary: "omp role map and the Artificial Analysis snapshot behind it", body: ompModels }
-}
+  overview: { summary: "What docks-kit is and how the pieces fit", body: overview },
+  "sync-layers": {
+    summary: "The three sync layers and additive-by-default semantics",
+    body: syncLayers,
+  },
+  flags: { summary: "Full flag reference incl. the old→new rename table", body: flags },
+  modifiers: {
+    summary: "Deploy-time modifiers and the flag-less-sync-reverts contract",
+    body: modifiers,
+  },
+  models: { summary: "Model catalog, validation rules, model get/set", body: models },
+  toolchain: { summary: "Verified-version floors and the doctor table", body: toolchain },
+  plugins: { summary: "enabledPlugins tri-state + optional plugin opt-ins", body: plugins },
+  install: {
+    summary: "Install paths: repo checkout, bun add -g, POSIX/Windows installers",
+    body: install,
+  },
+  platforms: {
+    summary: "Platform support: Linux, macOS, and Windows on x64 and arm64",
+    body: platforms,
+  },
+  "omp-models": {
+    summary: "omp role map and the Artificial Analysis snapshot behind it",
+    body: ompModels,
+  },
+};
 
 const topic = Argument.String("topic").pipe(
   Argument.withDescription(`One of: ${Object.keys(TOPICS).join(", ")}`),
-  Argument.optional
-)
+  Argument.optional,
+);
 const json = Flag.Boolean("json").pipe(
   Flag.withDescription("List topics as JSON"),
-  Flag.withDefault(false)
-)
+  Flag.withDefault(false),
+);
 
 export const docsCommand = Command.make("docs", { topic, json }, (config) =>
   Effect.gen(function* () {
-    const requested = Option.getOrUndefined(config.topic)
+    const requested = Option.getOrUndefined(config.topic);
 
     if (requested === undefined) {
       if (config.json) {
@@ -44,25 +59,25 @@ export const docsCommand = Command.make("docs", { topic, json }, (config) =>
           JSON.stringify(
             Object.entries(TOPICS).map(([name, t]) => ({ name, summary: t.summary })),
             null,
-            2
-          )
-        )
+            2,
+          ),
+        );
       }
-      yield* Console.log("docks-kit documentation topics (docks-kit docs <topic>):\n")
+      yield* Console.log("docks-kit documentation topics (docks-kit docs <topic>):\n");
       for (const [name, t] of Object.entries(TOPICS)) {
-        yield* Console.log(`  ${name.padEnd(14)} ${t.summary}`)
+        yield* Console.log(`  ${name.padEnd(14)} ${t.summary}`);
       }
-      return
+      return;
     }
 
-    const entry = TOPICS[requested]
+    const entry = TOPICS[requested];
     if (entry === undefined) {
-      return yield* bail(`Unknown topic '${requested}'. Valid: ${Object.keys(TOPICS).join(", ")}`)
+      return yield* bail(`Unknown topic '${requested}'. Valid: ${Object.keys(TOPICS).join(", ")}`);
     }
-    yield* Console.log(entry.body)
-  })
+    yield* Console.log(entry.body);
+  }),
 ).pipe(
   Command.withDescription(
-    "Self-documentation: the kit's concepts as readable topics, bundled with the CLI — a fresh agent can learn the kit from here alone."
-  )
-)
+    "Self-documentation: the kit's concepts as readable topics, bundled with the CLI — a fresh agent can learn the kit from here alone.",
+  ),
+);