argsbarg 4.0.4 → 4.1.1

package/src/install/target-scope.ts

@@ -0,0 +1,253 @@
+import { resolveCapabilities } from "../capabilities.ts";
+import { appConfigInstalled } from "../config/file.ts";
+import type { CliInstallTargets, CliProgram } from "../types.ts";
+import type { InstallPaths } from "./paths.ts";
+import {
+  type InstallPlanMode,
+  type InstallScope,
+  type InstallTargetPreview,
+  resolveAgentIntegration,
+  resolveEffectiveInstallTargets,
+  resolveInstallPlanMode,
+} from "./target-effective.ts";
+import {
+  INSTALL_ARTIFACT_KEYS,
+  INSTALL_TARGETS,
+  installTargetForKey,
+  MCP_KEYS,
+  SKILL_KEYS,
+} from "./target-registry.ts";
+import type {
+  CliInstallArtifactKey,
+  DetectedSnapshot,
+  InstalledArtifacts,
+  InstallOpts,
+  TargetPlanContext,
+} from "./target-types.ts";
+
+export { mcpCategoryEnabled } from "./target-effective.ts";
+
+function emptyInstalledArtifacts(): InstalledArtifacts {
+  return {
+    app: false,
+    cursorSkill: false,
+    claudeSkill: false,
+    codexSkill: false,
+    opencodeSkill: false,
+    openclawSkill: false,
+    cursorMcp: false,
+    claudeMcp: false,
+    claudeDesktopMcp: false,
+    opencodeMcp: false,
+    codexMcp: false,
+    openclawMcp: false,
+    chatGptMcp: false,
+  };
+}
+
+/** Detects which install artifacts are currently present. */
+export function detectInstalledArtifacts(
+  paths: InstallPaths,
+  root: CliProgram,
+): InstalledArtifacts {
+  const out = emptyInstalledArtifacts();
+  for (const target of INSTALL_TARGETS) {
+    target.applyDetected(paths, root, out);
+  }
+  return out;
+}
+
+/** Scope flags for install/uninstall. */
+export function resolveInstallScope(opts: InstallOpts): InstallScope {
+  return {
+    all: opts.all,
+    skill: opts.skill,
+    mcp: opts.mcp,
+    configure: opts.configure,
+    uninstall: opts.uninstall,
+  };
+}
+
+/** Builds detected snapshot including app config for plan scoping. */
+export function buildDetectedSnapshot(root: CliProgram, paths: InstallPaths): DetectedSnapshot {
+  const base = detectInstalledArtifacts(paths, root);
+  return {
+    ...base,
+    appConfig: root.appConfig ? appConfigInstalled(root) : false,
+  };
+}
+
+function targetExplicitlyConfigured(
+  user: CliInstallTargets | undefined,
+  key: CliInstallArtifactKey,
+): boolean {
+  return user?.[key] !== undefined;
+}
+
+function agentCategoryInScope(
+  key: CliInstallArtifactKey,
+  categoryKeys: readonly CliInstallArtifactKey[],
+  category: "skill" | "mcp",
+  effective: Record<CliInstallArtifactKey, { enabled: boolean; includedInAll: boolean }>,
+  targets: CliInstallTargets | undefined,
+  root: CliProgram,
+): boolean {
+  if (!categoryKeys.includes(key)) return false;
+  if (!effective[key].enabled) return false;
+  if (category === "mcp" && !resolveCapabilities(root).mcp) return false;
+  return effective[key].includedInAll || targetExplicitlyConfigured(targets, key);
+}
+
+/** Whether an artifact is in scope for the current CLI flags and install mode. */
+export function isArtifactInScope(
+  key: CliInstallArtifactKey,
+  scope: InstallScope,
+  effective: Record<CliInstallArtifactKey, { enabled: boolean; includedInAll: boolean }>,
+  mode: InstallPlanMode,
+  root: CliProgram,
+  targets?: CliInstallTargets,
+): boolean {
+  if (mode === "uninstall-all") {
+    return true;
+  }
+
+  if (mode === "refresh") {
+    return effective[key].enabled;
+  }
+
+  if (mode === "install-all") {
+    const t = effective[key];
+    return t.enabled && t.includedInAll;
+  }
+
+  if (mode === "uninstall-scoped" || mode === "install-scoped") {
+    if (!effective[key].enabled) return false;
+
+    let inScope = false;
+    if (scope.skill) {
+      inScope = inScope || agentCategoryInScope(key, SKILL_KEYS, "skill", effective, targets, root);
+    }
+    if (scope.mcp) {
+      inScope = inScope || agentCategoryInScope(key, MCP_KEYS, "mcp", effective, targets, root);
+    }
+    if (scope.configure && key === "configure") {
+      inScope = true;
+    }
+    return inScope;
+  }
+
+  return false;
+}
+
+/** Whether to include an artifact in the current install/uninstall/refresh plan. */
+export function shouldIncludeArtifact(
+  key: CliInstallArtifactKey,
+  root: CliProgram,
+  paths: InstallPaths,
+  scope: InstallScope,
+  mode: InstallPlanMode,
+  effective: Record<CliInstallArtifactKey, { enabled: boolean; includedInAll: boolean }>,
+  detected?: Partial<Record<CliInstallArtifactKey, boolean>>,
+): boolean {
+  const target = installTargetForKey(key);
+  const targets = root.install?.targets;
+
+  if (key !== "configure" && target && !target.isAvailable(root, paths)) {
+    return false;
+  }
+  if (key === "configure" && !root.appConfig) {
+    return false;
+  }
+  if (mode === "refresh" && detected) {
+    if (key === "app") {
+      // app is status-only; refresh skills/MCP only
+    } else if (!detected[key]) {
+      return false;
+    }
+  }
+  if ((mode === "uninstall-all" || mode === "uninstall-scoped") && detected) {
+    const det = detected[key];
+    if (key === "configure") {
+      if (!det) return false;
+    } else if (mode === "uninstall-scoped") {
+      if (!isArtifactInScope(key, scope, effective, mode, root, targets)) return false;
+      if (!det) return false;
+    } else if (!det) {
+      return false;
+    }
+  }
+  if (mode === "uninstall-all") {
+    return true;
+  }
+  if (mode === "uninstall-scoped") {
+    return isArtifactInScope(key, scope, effective, mode, root, targets);
+  }
+  if (mode === "refresh") {
+    if (key === "app") return false;
+    return effective[key].enabled;
+  }
+  return isArtifactInScope(key, scope, effective, mode, root, targets);
+}
+
+/** Builds plan context shared by install and uninstall planners. */
+export function buildTargetPlanContext(
+  root: CliProgram,
+  paths: InstallPaths,
+  opts: InstallOpts,
+  detected: DetectedSnapshot,
+): TargetPlanContext {
+  const effective = resolveEffectiveInstallTargets(root.install, root);
+  const mode = resolveInstallPlanMode(opts);
+  const scope = resolveInstallScope(opts);
+  const detPartial = Object.fromEntries(
+    INSTALL_TARGETS.map((t) => [t.key, t.detectedForSnapshot(detected)]),
+  ) as Partial<Record<CliInstallArtifactKey, boolean>>;
+
+  const include = (key: CliInstallArtifactKey) =>
+    shouldIncludeArtifact(key, root, paths, scope, mode, effective, detPartial);
+
+  return {
+    root,
+    paths,
+    opts,
+    dry: !!opts.dry,
+    detected,
+    effective,
+    scope,
+    mode,
+    include,
+  };
+}
+
+/** Maps detected snapshot to artifact key (for tests and legacy callers). */
+export function detectedForArtifact(
+  key: CliInstallArtifactKey,
+  detected: DetectedSnapshot,
+): boolean {
+  const target = installTargetForKey(key);
+  if (key === "configure") {
+    return detected.appConfig ?? false;
+  }
+  return target?.detectedForSnapshot(detected) ?? false;
+}
+
+/** Resolved artifact keys for `--all`, `--mcp`, and `--skill` (availability-gated). */
+export function resolveInstallTargetPreview(
+  program: CliProgram,
+  paths: InstallPaths,
+): InstallTargetPreview {
+  const effective = resolveEffectiveInstallTargets(program.install, program);
+  const integration = resolveAgentIntegration(program.install, program.mcpServer?.enabled === true);
+
+  const keysForScope = (scope: InstallScope, mode: InstallPlanMode): CliInstallArtifactKey[] =>
+    INSTALL_ARTIFACT_KEYS.filter((key) =>
+      shouldIncludeArtifact(key, program, paths, scope, mode, effective),
+    );
+
+  return {
+    agentIntegration: integration,
+    all: keysForScope({ all: true }, "install-all"),
+    mcp: keysForScope({ mcp: true }, "install-scoped"),
+    skill: keysForScope({ skill: true }, "install-scoped"),
+  };
+}

package/src/install/target-skill.ts

@@ -0,0 +1,104 @@
+import { existsSync } from "node:fs";
+import type { CliProgram } from "../types.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 SkillHostSpec {
+  key: CliInstallArtifactKey;
+  actionKind: InstallActionKind;
+  label: string;
+  uninstallPrefix: string;
+  pairedMcpKey: CliInstallArtifactKey;
+  skillDir: (paths: InstallPaths) => string;
+  detectedKey: keyof Pick<
+    InstalledArtifacts,
+    "cursorSkill" | "claudeSkill" | "codexSkill" | "opencodeSkill" | "openclawSkill"
+  >;
+  statusField: keyof Pick<
+    InstallStatus,
+    "cursorSkill" | "claudeSkill" | "codexSkill" | "opencodeSkill" | "openclawSkill"
+  >;
+  isAvailable: (root: CliProgram, paths: InstallPaths) => boolean;
+}
+
+/** Agent shell skill directory install. */
+export class SkillInstallTarget extends InstallTarget {
+  readonly key: CliInstallArtifactKey;
+  readonly actionKind: InstallActionKind;
+  readonly category = "skill" as const;
+  readonly pairedKey: CliInstallArtifactKey;
+  readonly uninstallPrefix: string;
+
+  private readonly spec: SkillHostSpec;
+
+  constructor(spec: SkillHostSpec) {
+    super();
+    this.spec = spec;
+    this.key = spec.key;
+    this.actionKind = spec.actionKind;
+    this.pairedKey = spec.pairedMcpKey;
+    this.uninstallPrefix = spec.uninstallPrefix;
+  }
+
+  isAvailable(root: CliProgram, paths: InstallPaths): boolean {
+    return this.spec.isAvailable(root, paths);
+  }
+
+  isDetected(paths: InstallPaths, _root: CliProgram): boolean {
+    return existsSync(this.spec.skillDir(paths));
+  }
+
+  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 {
+    return `${displayInstallPath(this.spec.skillDir(paths))}/`;
+  }
+
+  protected assignStatusLine(status: InstallStatus, line: string): void {
+    status[this.spec.statusField] = line;
+  }
+
+  skillDir(paths: InstallPaths): string {
+    return this.spec.skillDir(paths);
+  }
+
+  protected buildInstallActions(ctx: TargetPlanContext): InstallAction[] {
+    const dir = this.spec.skillDir(ctx.paths);
+    return [
+      {
+        kind: this.actionKind,
+        summary: `${this.spec.label.toLowerCase()} skill: ${displayInstallPath(dir)}/`,
+        message: `Installing ${this.spec.label} skill to ${displayInstallPath(dir)}/`,
+        run: () => [],
+      },
+    ];
+  }
+
+  protected buildUninstallActions(ctx: TargetPlanContext): UninstallAction[] {
+    const dir = this.spec.skillDir(ctx.paths);
+    return [
+      {
+        kind: this.actionKind,
+        summary: `${this.uninstallPrefix}: ${displayInstallPath(dir)}/`,
+        message: `Removing ${this.spec.label} skill ${displayInstallPath(dir)}/`,
+        run: () => [],
+      },
+    ];
+  }
+}

package/src/install/target-types.ts

@@ -0,0 +1,129 @@
+import type { CliProgram } from "../types.ts";
+import type { InstallPaths } from "./paths.ts";
+
+export type { InstallTargetSpec, ResolvedInstallTarget } from "../types.ts";
+
+export type InstallPlanMode =
+  | "install-all"
+  | "install-scoped"
+  | "uninstall-all"
+  | "uninstall-scoped"
+  | "refresh";
+
+export interface InstallScope {
+  all?: boolean;
+  skill?: boolean;
+  mcp?: boolean;
+  configure?: boolean;
+  uninstall?: boolean;
+}
+
+/** Artifact keys for install.targets. */
+export type CliInstallArtifactKey =
+  | "app"
+  | "chatgptMcp"
+  | "claudeCodeMcp"
+  | "claudeDesktopMcp"
+  | "claudeSkill"
+  | "codexMcp"
+  | "codexSkill"
+  | "configure"
+  | "cursorMcp"
+  | "cursorSkill"
+  | "openclawMcp"
+  | "openclawSkill"
+  | "opencodeMcp"
+  | "opencodeSkill";
+
+export type InstallActionKind =
+  | "app"
+  | "cursor-skill"
+  | "claude-skill"
+  | "codex-skill"
+  | "opencode-skill"
+  | "openclaw-skill"
+  | "cursor-mcp"
+  | "claude-mcp"
+  | "claude-desktop-mcp"
+  | "opencode-mcp"
+  | "codex-mcp"
+  | "openclaw-mcp"
+  | "chatgpt-desktop-mcp"
+  | "configure";
+
+export type InstallTargetCategory = "core" | "skill" | "mcp";
+
+export interface InstallAction {
+  kind: InstallActionKind;
+  summary: string;
+  message: string;
+  run: () => string[];
+}
+
+export interface UninstallAction {
+  kind?: InstallActionKind | "configure";
+  summary: string;
+  message: string;
+  run: () => string[];
+}
+
+export interface InstalledArtifacts {
+  app: boolean;
+  cursorSkill: boolean;
+  claudeSkill: boolean;
+  codexSkill: boolean;
+  opencodeSkill: boolean;
+  openclawSkill: boolean;
+  cursorMcp: boolean;
+  claudeMcp: boolean;
+  claudeDesktopMcp: boolean;
+  opencodeMcp: boolean;
+  codexMcp: boolean;
+  openclawMcp: boolean;
+  chatGptMcp: boolean;
+}
+
+export interface InstallStatus {
+  app?: string;
+  cursorSkill?: string;
+  claudeSkill?: string;
+  codexSkill?: string;
+  opencodeSkill?: string;
+  openclawSkill?: string;
+  cursorMcp?: string;
+  claudeMcp?: string;
+  claudeDesktopMcp?: string;
+  opencodeMcp?: string;
+  codexMcp?: string;
+  openclawMcp?: string;
+  chatGptMcp?: string;
+}
+
+export interface DetectedSnapshot extends InstalledArtifacts {
+  appConfig?: boolean;
+}
+
+export interface InstallOpts {
+  all?: boolean;
+  skill?: boolean;
+  mcp?: boolean;
+  reinstall?: boolean;
+  status?: boolean;
+  uninstall?: boolean;
+  configure?: boolean;
+  yes?: boolean;
+  dry?: boolean;
+  json?: boolean;
+}
+
+export interface TargetPlanContext {
+  root: CliProgram;
+  paths: InstallPaths;
+  opts: InstallOpts;
+  dry: boolean;
+  detected: DetectedSnapshot;
+  effective: Record<CliInstallArtifactKey, { enabled: boolean; includedInAll: boolean }>;
+  scope: InstallScope;
+  mode: InstallPlanMode;
+  include: (key: CliInstallArtifactKey) => boolean;
+}

package/src/install/targets/app.ts

@@ -0,0 +1,60 @@
+import type { CliProgram } from "../../types.ts";
+import { isExternallyManagedBinary } from "../binary-placement.ts";
+import { displayInstallPath, type InstallPaths } from "../paths.ts";
+import { InstallTarget } from "../target-base.ts";
+import type {
+  DetectedSnapshot,
+  InstallAction,
+  InstalledArtifacts,
+  InstallStatus,
+  TargetPlanContext,
+  UninstallAction,
+} from "../target-types.ts";
+
+/** Reports app install location (Homebrew PATH or legacy ~/.local/bin). No self-install actions. */
+class AppInstallTarget extends InstallTarget {
+  readonly key = "app" as const;
+  readonly actionKind = "app" as const;
+  readonly category = "core" as const;
+
+  defaultIncludedInAll(): boolean {
+    return false;
+  }
+
+  isAvailable(_root: CliProgram, _paths: InstallPaths): boolean {
+    return true;
+  }
+
+  isDetected(paths: InstallPaths, root: CliProgram): boolean {
+    return isExternallyManagedBinary(root.key) || false;
+  }
+
+  applyDetected(_paths: InstallPaths, root: CliProgram, out: InstalledArtifacts): void {
+    out.app = isExternallyManagedBinary(root.key);
+  }
+
+  protected isDetectedFromSnapshot(detected: DetectedSnapshot): boolean {
+    return detected.app;
+  }
+
+  protected formatStatusLine(_paths: InstallPaths, root: CliProgram): string {
+    if (isExternallyManagedBinary(root.key)) {
+      return "system (PATH)";
+    }
+    return "not installed (use Homebrew)";
+  }
+
+  protected assignStatusLine(status: InstallStatus, line: string): void {
+    status.app = line;
+  }
+
+  protected buildInstallActions(_ctx: TargetPlanContext): InstallAction[] {
+    return [];
+  }
+
+  protected buildUninstallActions(_ctx: TargetPlanContext): UninstallAction[] {
+    return [];
+  }
+}
+
+export const appTarget = new AppInstallTarget();

package/src/install/targets/chatgpt-mcp.ts

@@ -0,0 +1,12 @@
+import { chatGptDesktopPresent, userHome } from "../paths.ts";
+import { McpJsonInstallTarget } from "../target-mcp-json.ts";
+
+export const chatgptMcpTarget = new McpJsonInstallTarget({
+  key: "chatgptMcp",
+  actionKind: "chatgpt-desktop-mcp",
+  label: "chatgpt desktop mcp",
+  configPath: (p) => p.chatGptMcpPath,
+  detectedKey: "chatGptMcp",
+  statusField: "chatGptMcp",
+  isAvailable: (_root, paths) => chatGptDesktopPresent(userHome(), paths.chatGptMcpPath),
+});

package/src/install/targets/claude-code-mcp.ts

@@ -0,0 +1,15 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { userHome } from "../paths.ts";
+import { McpJsonInstallTarget } from "../target-mcp-json.ts";
+
+export const claudeCodeMcpTarget = new McpJsonInstallTarget({
+  key: "claudeCodeMcp",
+  actionKind: "claude-mcp",
+  label: "claude code mcp",
+  pairedSkillKey: "claudeSkill",
+  configPath: (p) => p.claudeMcpPath,
+  detectedKey: "claudeMcp",
+  statusField: "claudeMcp",
+  isAvailable: () => existsSync(join(userHome(), ".claude")),
+});

package/src/install/targets/claude-desktop-mcp.ts

@@ -0,0 +1,12 @@
+import { claudeDesktopPresent, userHome } from "../paths.ts";
+import { McpJsonInstallTarget } from "../target-mcp-json.ts";
+
+export const claudeDesktopMcpTarget = new McpJsonInstallTarget({
+  key: "claudeDesktopMcp",
+  actionKind: "claude-desktop-mcp",
+  label: "claude desktop mcp",
+  configPath: (p) => p.claudeDesktopMcpPath,
+  detectedKey: "claudeDesktopMcp",
+  statusField: "claudeDesktopMcp",
+  isAvailable: (_root, paths) => claudeDesktopPresent(userHome(), paths.claudeDesktopMcpPath),
+});

package/src/install/targets/claude-skill.ts

@@ -0,0 +1,16 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { userHome } from "../paths.ts";
+import { SkillInstallTarget } from "../target-skill.ts";
+
+export const claudeSkillTarget = new SkillInstallTarget({
+  key: "claudeSkill",
+  actionKind: "claude-skill",
+  label: "Claude Code",
+  uninstallPrefix: "claude skill",
+  pairedMcpKey: "claudeCodeMcp",
+  skillDir: (p) => p.claudeSkillDir,
+  detectedKey: "claudeSkill",
+  statusField: "claudeSkill",
+  isAvailable: () => existsSync(join(userHome(), ".claude")),
+});

package/src/install/targets/codex-mcp.ts

@@ -0,0 +1,25 @@
+import { codexOnPath } from "../mcp-codex.ts";
+import {
+  checkCodexMcpConflict,
+  codexMcpHasServer,
+  McpCliInstallTarget,
+  mergeCodexMcpConfig,
+  removeCodexMcpConfig,
+} from "../target-mcp-cli.ts";
+
+export const codexMcpTarget = new McpCliInstallTarget({
+  key: "codexMcp",
+  actionKind: "codex-mcp",
+  label: "codex mcp",
+  pairedSkillKey: "codexSkill",
+  configPath: (p) => p.codexConfigPath,
+  detectedKey: "codexMcp",
+  statusField: "codexMcp",
+  isAvailable: () => codexOnPath(),
+  hasServer: codexMcpHasServer,
+  installMessage: 'Registering MCP server "{name}" via codex mcp add',
+  uninstallMessage: 'Removing MCP server "{name}" from Codex via codex mcp remove',
+  merge: mergeCodexMcpConfig,
+  remove: removeCodexMcpConfig,
+  preflight: checkCodexMcpConflict,
+});

package/src/install/targets/codex-skill.ts

@@ -0,0 +1,14 @@
+import { codexOnPath } from "../mcp-codex.ts";
+import { SkillInstallTarget } from "../target-skill.ts";
+
+export const codexSkillTarget = new SkillInstallTarget({
+  key: "codexSkill",
+  actionKind: "codex-skill",
+  label: "Codex",
+  uninstallPrefix: "codex skill",
+  pairedMcpKey: "codexMcp",
+  skillDir: (p) => p.codexSkillDir,
+  detectedKey: "codexSkill",
+  statusField: "codexSkill",
+  isAvailable: () => codexOnPath(),
+});