argsbarg 4.0.4 → 4.1.1

package/src/install/target-effective.ts

@@ -0,0 +1,129 @@
+import { resolveCapabilities } from "../capabilities.ts";
+import type {
+  CliInstallConfig,
+  CliInstallTargets,
+  CliProgram,
+  InstallAgentIntegration,
+  InstallTargetSpec,
+} from "../types.ts";
+import type { InstallPaths } from "./paths.ts";
+import { AGENT_PAIRS, INSTALL_ARTIFACT_KEYS, installTargetForKey } from "./target-registry.ts";
+import type { CliInstallArtifactKey, InstallPlanMode } from "./target-types.ts";
+
+export type { InstallTargetSpec, ResolvedInstallTarget } from "../types.ts";
+
+export type { InstallPlanMode, InstallScope } from "./target-types.ts";
+
+export function resolveAgentIntegration(
+  install?: CliInstallConfig,
+  mcpEnabled = false,
+): InstallAgentIntegration {
+  return install?.agentIntegration ?? (mcpEnabled ? "mcp" : "skill");
+}
+
+/** Resolves a boolean or object target spec against category defaults. */
+export function resolveInstallTargetSpec(
+  spec: InstallTargetSpec | undefined,
+  defaults: { enabled: boolean; includedInAll: boolean },
+): { enabled: boolean; includedInAll: boolean } {
+  if (spec === undefined) {
+    return { ...defaults };
+  }
+  if (typeof spec === "boolean") {
+    return {
+      enabled: spec,
+      includedInAll: spec ? defaults.includedInAll : false,
+    };
+  }
+  return {
+    enabled: spec.enabled ?? defaults.enabled,
+    includedInAll: spec.includedInAll ?? defaults.includedInAll,
+  };
+}
+
+function artifactDefaults(
+  key: CliInstallArtifactKey,
+  integration: InstallAgentIntegration,
+): { enabled: boolean; includedInAll: boolean } {
+  const target = installTargetForKey(key);
+  const includedInAll = target?.defaultIncludedInAll(integration) ?? false;
+  return { enabled: true, includedInAll };
+}
+
+function applyAgentPairDedupe(
+  out: Record<CliInstallArtifactKey, { enabled: boolean; includedInAll: boolean }>,
+  user: CliInstallTargets | undefined,
+  integration: InstallAgentIntegration,
+): void {
+  if (integration === "both") return;
+
+  for (const [mcpKey, skillKey] of AGENT_PAIRS) {
+    const mcp = out[mcpKey];
+    const skill = out[skillKey];
+    if (!mcp.includedInAll || !skill.includedInAll) continue;
+
+    const mcpKeyExplicit = user?.[mcpKey] !== undefined;
+    const skillKeyExplicit = user?.[skillKey] !== undefined;
+
+    if (mcpKeyExplicit && !skillKeyExplicit) continue;
+    if (skillKeyExplicit && !mcpKeyExplicit) continue;
+
+    if (integration === "mcp") {
+      out[skillKey] = { ...skill, includedInAll: false };
+    } else {
+      out[mcpKey] = { ...mcp, includedInAll: false };
+    }
+  }
+}
+
+/** Effective per-artifact gates for install.targets. */
+export function resolveEffectiveInstallTargets(
+  install?: CliInstallConfig,
+  program?: Pick<CliProgram, "mcpServer">,
+): Record<CliInstallArtifactKey, { enabled: boolean; includedInAll: boolean }> {
+  const mcpEnabled = program?.mcpServer?.enabled === true;
+  const integration = resolveAgentIntegration(install, mcpEnabled);
+  const user = install?.targets;
+  const out = {} as Record<CliInstallArtifactKey, { enabled: boolean; includedInAll: boolean }>;
+  for (const key of INSTALL_ARTIFACT_KEYS) {
+    out[key] = resolveInstallTargetSpec(user?.[key], artifactDefaults(key, integration));
+  }
+  applyAgentPairDedupe(out, user, integration);
+  return out;
+}
+
+/** MCP enabled check for scoped uninstall/install mcp category. */
+export function mcpCategoryEnabled(root: CliProgram): boolean {
+  return resolveCapabilities(root).mcp;
+}
+
+export interface InstallTargetPreview {
+  agentIntegration: InstallAgentIntegration;
+  all: CliInstallArtifactKey[];
+  mcp: CliInstallArtifactKey[];
+  skill: CliInstallArtifactKey[];
+}
+
+/** Derives plan mode from install CLI flags. */
+export function resolveInstallPlanMode(opts: {
+  all?: boolean;
+  skill?: boolean;
+  mcp?: boolean;
+  configure?: boolean;
+  uninstall?: boolean;
+  reinstall?: boolean;
+}): InstallPlanMode {
+  if (opts.reinstall) return "refresh";
+  if (opts.uninstall) return opts.all ? "uninstall-all" : "uninstall-scoped";
+  if (opts.all) return "install-all";
+  return "install-scoped";
+}
+
+/** @deprecated Use target registry. */
+export function isInstallTargetAvailable(
+  key: CliInstallArtifactKey,
+  root: CliProgram,
+  paths: InstallPaths,
+): boolean {
+  return installTargetForKey(key)?.isAvailable(root, paths) ?? false;
+}

package/src/install/target-mcp-cli.ts

@@ -0,0 +1,149 @@
+import type { CliProgram } from "../types.ts";
+import {
+  checkCodexMcpConflict,
+  codexMcpHasServer,
+  mergeCodexMcpConfig,
+  removeCodexMcpConfig,
+} from "./mcp-codex.ts";
+import { expectedMcpEntry } from "./mcp-config.ts";
+import {
+  checkOpenclawMcpConflict,
+  mergeOpenclawMcpConfig,
+  openclawMcpHasServer,
+  removeOpenclawMcpConfig,
+} from "./mcp-openclaw.ts";
+import { displayInstallPath, type InstallPaths, userHome } from "./paths.ts";
+import { InstallTarget } from "./target-base.ts";
+import type {
+  CliInstallArtifactKey,
+  DetectedSnapshot,
+  InstallAction,
+  InstallActionKind,
+  InstalledArtifacts,
+  InstallStatus,
+  TargetPlanContext,
+  UninstallAction,
+} from "./target-types.ts";
+
+export interface McpCliHostSpec {
+  key: CliInstallArtifactKey;
+  actionKind: InstallActionKind;
+  label: string;
+  pairedSkillKey: CliInstallArtifactKey;
+  configPath: (paths: InstallPaths) => string;
+  detectedKey: "codexMcp" | "openclawMcp";
+  statusField: "codexMcp" | "openclawMcp";
+  isAvailable: (root: CliProgram, paths: InstallPaths) => boolean;
+  hasServer: (home: string, name: string) => boolean;
+  installMessage: string;
+  uninstallMessage: string;
+  merge: (
+    home: string,
+    name: string,
+    entry: ReturnType<typeof expectedMcpEntry>,
+    dry: boolean,
+    yes: boolean,
+  ) => string;
+  remove: (home: string, name: string, dry: boolean) => void;
+  preflight: (
+    home: string,
+    name: string,
+    entry: ReturnType<typeof expectedMcpEntry>,
+    yes: boolean,
+  ) => string | null;
+}
+
+/** MCP host registered via an external CLI (codex, openclaw). */
+export class McpCliInstallTarget extends InstallTarget {
+  readonly key: CliInstallArtifactKey;
+  readonly actionKind: InstallActionKind;
+  readonly category = "mcp" as const;
+  readonly pairedKey: CliInstallArtifactKey;
+
+  private readonly spec: McpCliHostSpec;
+
+  constructor(spec: McpCliHostSpec) {
+    super();
+    this.spec = spec;
+    this.key = spec.key;
+    this.actionKind = spec.actionKind;
+    this.pairedKey = spec.pairedSkillKey;
+  }
+
+  isAvailable(root: CliProgram, paths: InstallPaths): boolean {
+    return this.spec.isAvailable(root, paths);
+  }
+
+  isDetected(paths: InstallPaths, _root: CliProgram): boolean {
+    return this.spec.hasServer(userHome(), paths.mcpName);
+  }
+
+  applyDetected(paths: InstallPaths, root: CliProgram, out: InstalledArtifacts): void {
+    out[this.spec.detectedKey] = this.isDetected(paths, root);
+  }
+
+  protected isDetectedFromSnapshot(detected: DetectedSnapshot): boolean {
+    return detected[this.spec.detectedKey] ?? false;
+  }
+
+  protected formatStatusLine(paths: InstallPaths, _root: CliProgram): string {
+    return `${displayInstallPath(this.spec.configPath(paths))} (server "${paths.mcpName}")`;
+  }
+
+  protected assignStatusLine(status: InstallStatus, line: string): void {
+    status[this.spec.statusField] = line;
+  }
+
+  preflight(ctx: TargetPlanContext): string | null {
+    const entry = expectedMcpEntry(ctx.root);
+    return this.spec.preflight(userHome(), ctx.paths.mcpName, entry, !!ctx.opts.yes);
+  }
+
+  protected buildInstallActions(ctx: TargetPlanContext): InstallAction[] {
+    const entry = expectedMcpEntry(ctx.root);
+    const configPath = this.spec.configPath(ctx.paths);
+    return [
+      {
+        kind: this.actionKind,
+        summary: `${this.spec.label}: ${displayInstallPath(configPath)}`,
+        message: this.spec.installMessage.replace("{name}", ctx.paths.mcpName),
+        run: () => {
+          const written = this.spec.merge(
+            userHome(),
+            ctx.paths.mcpName,
+            entry,
+            ctx.dry,
+            !!ctx.opts.yes,
+          );
+          return [written];
+        },
+      },
+    ];
+  }
+
+  protected buildUninstallActions(ctx: TargetPlanContext): UninstallAction[] {
+    const configPath = this.spec.configPath(ctx.paths);
+    return [
+      {
+        kind: this.actionKind,
+        summary: `${this.spec.label}: ${displayInstallPath(configPath)}`,
+        message: this.spec.uninstallMessage.replace("{name}", ctx.paths.mcpName),
+        run: () => {
+          this.spec.remove(userHome(), ctx.paths.mcpName, ctx.dry);
+          return [configPath];
+        },
+      },
+    ];
+  }
+}
+
+export {
+  checkCodexMcpConflict,
+  checkOpenclawMcpConflict,
+  codexMcpHasServer,
+  mergeCodexMcpConfig,
+  mergeOpenclawMcpConfig,
+  openclawMcpHasServer,
+  removeCodexMcpConfig,
+  removeOpenclawMcpConfig,
+};

package/src/install/target-mcp-json.ts

@@ -0,0 +1,130 @@
+import type { CliProgram } from "../types.ts";
+import {
+  checkMcpConflict,
+  expectedMcpEntry,
+  mergeMcpConfig,
+  readMcpServerEntry,
+  removeMcpConfig,
+} from "./mcp-config.ts";
+import { displayInstallPath, type InstallPaths } from "./paths.ts";
+import { InstallTarget } from "./target-base.ts";
+import type {
+  CliInstallArtifactKey,
+  DetectedSnapshot,
+  InstallAction,
+  InstallActionKind,
+  InstalledArtifacts,
+  InstallStatus,
+  TargetPlanContext,
+  UninstallAction,
+} from "./target-types.ts";
+
+export interface McpJsonHostSpec {
+  key: CliInstallArtifactKey;
+  actionKind: InstallActionKind;
+  label: string;
+  pairedSkillKey?: CliInstallArtifactKey;
+  configPath: (paths: InstallPaths) => string;
+  detectedKey: keyof Pick<
+    InstalledArtifacts,
+    "cursorMcp" | "claudeMcp" | "claudeDesktopMcp" | "chatGptMcp"
+  >;
+  statusField: keyof Pick<
+    InstallStatus,
+    "cursorMcp" | "claudeMcp" | "claudeDesktopMcp" | "chatGptMcp"
+  >;
+  isAvailable: (root: CliProgram, paths: InstallPaths) => boolean;
+  /** Append server name to status line (default false). */
+  statusIncludesServer?: boolean;
+}
+
+function mcpConfigHasServer(path: string, name: string): boolean {
+  return readMcpServerEntry(path, name) !== undefined;
+}
+
+/** MCP host that merges into a JSON `mcpServers` config file. */
+export class McpJsonInstallTarget extends InstallTarget {
+  readonly key: CliInstallArtifactKey;
+  readonly actionKind: InstallActionKind;
+  readonly category = "mcp" as const;
+  readonly pairedKey?: CliInstallArtifactKey;
+
+  private readonly spec: McpJsonHostSpec;
+
+  constructor(spec: McpJsonHostSpec) {
+    super();
+    this.spec = spec;
+    this.key = spec.key;
+    this.actionKind = spec.actionKind;
+    this.pairedKey = spec.pairedSkillKey;
+  }
+
+  isAvailable(root: CliProgram, paths: InstallPaths): boolean {
+    return this.spec.isAvailable(root, paths);
+  }
+
+  isDetected(paths: InstallPaths, _root: CliProgram): boolean {
+    return mcpConfigHasServer(this.spec.configPath(paths), paths.mcpName);
+  }
+
+  applyDetected(paths: InstallPaths, root: CliProgram, out: InstalledArtifacts): void {
+    out[this.spec.detectedKey] = this.isDetected(paths, root);
+  }
+
+  protected isDetectedFromSnapshot(detected: DetectedSnapshot): boolean {
+    return detected[this.spec.detectedKey];
+  }
+
+  protected formatStatusLine(paths: InstallPaths, _root: CliProgram): string {
+    const path = displayInstallPath(this.spec.configPath(paths));
+    if (this.spec.statusIncludesServer) {
+      return `${path} (server "${paths.mcpName}")`;
+    }
+    return path;
+  }
+
+  protected assignStatusLine(status: InstallStatus, line: string): void {
+    status[this.spec.statusField] = line;
+  }
+
+  preflight(ctx: TargetPlanContext): string | null {
+    const entry = expectedMcpEntry(ctx.root);
+    return checkMcpConflict(
+      this.spec.configPath(ctx.paths),
+      ctx.paths.mcpName,
+      entry,
+      !!ctx.opts.yes,
+    );
+  }
+
+  protected buildInstallActions(ctx: TargetPlanContext): InstallAction[] {
+    const configPath = this.spec.configPath(ctx.paths);
+    const entry = expectedMcpEntry(ctx.root);
+    return [
+      {
+        kind: this.actionKind,
+        summary: `${this.spec.label}: ${displayInstallPath(configPath)}`,
+        message: `Merging MCP server "${ctx.paths.mcpName}" into ${displayInstallPath(configPath)}`,
+        run: () => {
+          mergeMcpConfig(configPath, ctx.paths.mcpName, entry, ctx.dry);
+          return [configPath];
+        },
+      },
+    ];
+  }
+
+  protected buildUninstallActions(ctx: TargetPlanContext): UninstallAction[] {
+    const configPath = this.spec.configPath(ctx.paths);
+    return [
+      {
+        kind: this.actionKind,
+        summary: `${this.spec.label}: ${displayInstallPath(configPath)}`,
+        message: `Removing MCP server "${ctx.paths.mcpName}" from ${displayInstallPath(configPath)}`,
+        run: () => {
+          removeMcpConfig(configPath, ctx.paths.mcpName, ctx.dry);
+          return [configPath];
+        },
+      },
+    ];
+  }
+}

package/src/install/target-plan-build.ts

@@ -0,0 +1,67 @@
+import { resolveCapabilities } from "../capabilities.ts";
+import type { CliProgram } from "../types.ts";
+import type { InstallPaths } from "./paths.ts";
+import { mcpCategoryEnabled } from "./target-effective.ts";
+import { INSTALL_TARGETS, installTargetForKey } from "./target-registry.ts";
+import { buildDetectedSnapshot, buildTargetPlanContext } from "./target-scope.ts";
+import type { InstallAction, InstallOpts, UninstallAction } from "./target-types.ts";
+
+/** Builds install actions for normal mode (--all / scoped targets). */
+export function buildInstallPlanFromTargets(
+  root: CliProgram,
+  paths: InstallPaths,
+  opts: InstallOpts,
+): InstallAction[] {
+  const detected = buildDetectedSnapshot(root, paths);
+  const ctx = buildTargetPlanContext(root, paths, opts, detected);
+
+  const actions: InstallAction[] = [];
+  const mcpEnabled = mcpCategoryEnabled(root);
+
+  for (const target of INSTALL_TARGETS) {
+    if (target.category === "mcp" && !mcpEnabled) continue;
+    actions.push(...target.planInstall(ctx));
+  }
+  return actions;
+}
+
+/** Builds uninstall actions for scoped targets or --all. */
+export function buildUninstallPlanFromTargets(
+  root: CliProgram,
+  paths: InstallPaths,
+  opts: InstallOpts,
+): UninstallAction[] {
+  const detected = buildDetectedSnapshot(root, paths);
+  const ctx = buildTargetPlanContext(root, paths, opts, detected);
+
+  const actions: UninstallAction[] = [];
+  for (const target of INSTALL_TARGETS) {
+    if (target.key === "configure") continue;
+    actions.push(...target.planUninstall(ctx));
+  }
+  const configure = installTargetForKey("configure");
+  if (configure) {
+    actions.push(...configure.planUninstall(ctx));
+  }
+  return actions;
+}
+
+/** Runs MCP preflight for planned install actions. */
+export function runTargetPreflight(
+  root: CliProgram,
+  paths: InstallPaths,
+  opts: InstallOpts,
+  actions: InstallAction[],
+): void {
+  if (!resolveCapabilities(root).mcp) return;
+
+  const kinds = new Set(actions.map((a) => a.kind));
+  const detected = buildDetectedSnapshot(root, paths);
+  const ctx = buildTargetPlanContext(root, paths, opts, detected);
+
+  for (const target of INSTALL_TARGETS) {
+    if (!target.preflight || !kinds.has(target.actionKind)) continue;
+    const err = target.preflight(ctx);
+    if (err) throw new Error(err);
+  }
+}

package/src/install/target-registry.ts

@@ -0,0 +1,57 @@
+import type { InstallTarget } from "./target-base.ts";
+import type { SkillInstallTarget } from "./target-skill.ts";
+import type { CliInstallArtifactKey, InstallActionKind } from "./target-types.ts";
+import { INSTALL_TARGETS } from "./targets/index.ts";
+
+export { INSTALL_TARGETS } from "./targets/index.ts";
+
+export const INSTALL_ARTIFACT_KEYS: CliInstallArtifactKey[] = INSTALL_TARGETS.map((t) => t.key);
+
+export const SKILL_KEYS: CliInstallArtifactKey[] = INSTALL_TARGETS.filter(
+  (t) => t.category === "skill",
+).map((t) => t.key);
+
+export const MCP_KEYS: CliInstallArtifactKey[] = INSTALL_TARGETS.filter(
+  (t) => t.category === "mcp",
+).map((t) => t.key);
+
+/** Maps plan action kinds to install.targets artifact keys. */
+export const ACTION_KIND_TO_ARTIFACT: Record<InstallActionKind, CliInstallArtifactKey> =
+  Object.fromEntries(INSTALL_TARGETS.map((t) => [t.actionKind, t.key])) as Record<
+    InstallActionKind,
+    CliInstallArtifactKey
+  >;
+
+/** Hosts with both MCP config and shell skill install targets. */
+export const AGENT_PAIRS: [CliInstallArtifactKey, CliInstallArtifactKey][] =
+  INSTALL_TARGETS.flatMap((t) =>
+    t.category === "mcp" && t.pairedKey !== undefined
+      ? [[t.key, t.pairedKey] as [CliInstallArtifactKey, CliInstallArtifactKey]]
+      : [],
+  );
+
+const targetByKey = new Map(INSTALL_TARGETS.map((t) => [t.key, t]));
+
+/** Lookup a registered install target by artifact key. */
+export function installTargetForKey(key: CliInstallArtifactKey): InstallTarget | undefined {
+  return targetByKey.get(key);
+}
+
+/** Lookup by plan action kind. */
+export function installTargetForActionKind(kind: InstallActionKind): InstallTarget | undefined {
+  return INSTALL_TARGETS.find((t) => t.actionKind === kind);
+}
+
+/** Skill targets for uninstall summary → directory resolution. */
+export function skillTargetForUninstallSummary(summary: string): SkillInstallTarget | undefined {
+  for (const t of INSTALL_TARGETS) {
+    if (
+      t.category === "skill" &&
+      (t as SkillInstallTarget).uninstallPrefix &&
+      summary.startsWith((t as SkillInstallTarget).uninstallPrefix)
+    ) {
+      return t as SkillInstallTarget;
+    }
+  }
+  return undefined;
+}