@indy2kro/agentenv 0.1.0

package/dist/integrations/superpowers.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Superpowers Integration Adapter
+ * Installs github:obra/superpowers for Claude Code only, via `claude plugin
+ * marketplace add` / `claude plugin install` — the only agent with a
+ * documented, non-interactive, ref-pinnable installer. See
+ * docs/research/superpowers-install-mechanisms.md for the other three
+ * agents, which always report `unsupported` and never execute a command.
+ */
+import type { IntegrationConfig } from '../config/schema.js';
+import type { IntegrationAdapter, IntegrationResult } from './base.js';
+export declare const SUPERPOWERS_MARKETPLACE_REPO = "obra/superpowers-marketplace";
+export declare const SUPERPOWERS_PLUGIN_ID = "superpowers@superpowers-marketplace";
+export interface ClaudeCliCommandResult {
+    success: boolean;
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+}
+/** Injectable so tests never spawn a real `claude` binary. */
+export type ClaudeCliRunner = (args: string[], cwd: string) => ClaudeCliCommandResult;
+interface FsDeps {
+    existsSync: (path: string) => boolean;
+    readFileSync: (path: string, encoding: 'utf-8') => string;
+    writeFileSync: (path: string, content: string) => void;
+    mkdirSync: (path: string, opts?: {
+        recursive?: boolean;
+    }) => void;
+}
+export interface SuperpowersAdapterDeps {
+    runClaudeCli?: ClaudeCliRunner;
+    fs?: FsDeps;
+}
+export declare class SuperpowersAdapter implements IntegrationAdapter {
+    private readonly runClaudeCli;
+    private readonly fsImpl;
+    constructor(deps?: SuperpowersAdapterDeps);
+    getName(): string;
+    isEnabled(config: IntegrationConfig | undefined): boolean;
+    private markerPath;
+    private readMarker;
+    private writeMarker;
+    private detectClaudeCode;
+    detect(baseDir: string, config: IntegrationConfig | undefined): Promise<IntegrationResult>;
+    status(baseDir: string, config: IntegrationConfig | undefined): Promise<IntegrationResult>;
+    apply(baseDir: string, config: IntegrationConfig | undefined): Promise<IntegrationResult>;
+}
+export {};
+//# sourceMappingURL=superpowers.d.ts.map

package/dist/integrations/superpowers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"superpowers.d.ts","sourceRoot":"","sources":["../../src/integrations/superpowers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EAAY,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAyB,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9F,eAAO,MAAM,4BAA4B,iCAAiC,CAAC;AAC3E,eAAO,MAAM,qBAAqB,wCAAwC,CAAC;AAW3E,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,8DAA8D;AAC9D,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,KAAK,sBAAsB,CAAC;AA6BtF,UAAU,MAAM;IACd,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACtC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,KAAK,MAAM,CAAC;IAC1D,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACvD,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;CACnE;AAED,MAAM,WAAW,sBAAsB;IACrC,YAAY,CAAC,EAAE,eAAe,CAAC;IAC/B,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAQD,qBAAa,kBAAmB,YAAW,kBAAkB;IAC3D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkB;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,IAAI,GAAE,sBAA2B;IAK7C,OAAO,IAAI,MAAM;IAIjB,SAAS,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,GAAG,OAAO;IAIzD,OAAO,CAAC,UAAU;IAOlB,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,gBAAgB;IAmClB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,SAAS,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAyB1F,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,SAAS,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAI1F,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,SAAS,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAmEhG"}

package/dist/integrations/superpowers.js

@@ -0,0 +1,191 @@
+/**
+ * Superpowers Integration Adapter
+ * Installs github:obra/superpowers for Claude Code only, via `claude plugin
+ * marketplace add` / `claude plugin install` — the only agent with a
+ * documented, non-interactive, ref-pinnable installer. See
+ * docs/research/superpowers-install-mechanisms.md for the other three
+ * agents, which always report `unsupported` and never execute a command.
+ */
+import * as child_process from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { resolveBinary } from '../adapters/detect.js';
+import { AGENT_KEYS, resolveIntegrationScope } from '../config/schema.js';
+export const SUPERPOWERS_MARKETPLACE_REPO = 'obra/superpowers-marketplace';
+export const SUPERPOWERS_PLUGIN_ID = 'superpowers@superpowers-marketplace';
+const MANUAL_INSTALL_HINTS = {
+    codex_cli: 'No non-interactive install is documented for Codex CLI. In an interactive Codex session, run /plugins, search "superpowers", and select Install Plugin.',
+    copilot: 'Upstream documents `copilot plugin marketplace add obra/superpowers-marketplace` then `copilot plugin install superpowers@superpowers-marketplace`, but no ref-pin mechanism is documented, so agentenv does not run this automatically. See docs/research/superpowers-install-mechanisms.md.',
+    opencode: 'OpenCode installation is driven by instructions fetched from .opencode/INSTALL.md in the Superpowers repo, which has no fixed command agentenv can safely automate. Follow that file manually.',
+};
+const defaultClaudeCliRunner = (args, cwd) => {
+    const claudePath = resolveBinary('claude');
+    if (!claudePath) {
+        return { success: false, exitCode: null, stdout: '', stderr: 'claude CLI not found on PATH' };
+    }
+    try {
+        const result = child_process.spawnSync(claudePath, args, {
+            cwd,
+            encoding: 'utf-8',
+            stdio: 'pipe',
+        });
+        return {
+            success: result.status === 0,
+            exitCode: result.status,
+            stdout: result.stdout || '',
+            stderr: result.stderr || '',
+        };
+    }
+    catch (err) {
+        return {
+            success: false,
+            exitCode: null,
+            stdout: '',
+            stderr: err instanceof Error ? err.message : String(err),
+        };
+    }
+};
+export class SuperpowersAdapter {
+    constructor(deps = {}) {
+        this.runClaudeCli = deps.runClaudeCli ?? defaultClaudeCliRunner;
+        this.fsImpl = deps.fs ?? fs;
+    }
+    getName() {
+        return 'Superpowers';
+    }
+    isEnabled(config) {
+        return config?.enabled === true;
+    }
+    markerPath(baseDir) {
+        // path.posix rather than the platform `path` module: baseDir may be a
+        // logical (test-injected) identifier rather than an OS path, and Node's
+        // fs functions accept forward slashes on Windows regardless.
+        return path.posix.join(baseDir, '.agentenv-state', 'integrations', 'superpowers.json');
+    }
+    readMarker(baseDir) {
+        const file = this.markerPath(baseDir);
+        if (!this.fsImpl.existsSync(file))
+            return undefined;
+        try {
+            return JSON.parse(this.fsImpl.readFileSync(file, 'utf-8'));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    writeMarker(baseDir, marker) {
+        const file = this.markerPath(baseDir);
+        this.fsImpl.mkdirSync(path.posix.dirname(file), { recursive: true });
+        this.fsImpl.writeFileSync(file, JSON.stringify(marker, null, 2));
+    }
+    detectClaudeCode(baseDir, config) {
+        const list = this.runClaudeCli(['plugin', 'list'], baseDir);
+        if (!list.success && list.exitCode === null) {
+            return {
+                agent: 'claude_code',
+                state: 'unsupported',
+                detail: list.stderr || 'claude CLI not found on PATH',
+            };
+        }
+        // `claude plugin list` has no documented structured-output flag; this is
+        // a best-effort text match on the plugin name. Revisit if a --json flag
+        // is documented.
+        const installed = list.stdout.toLowerCase().includes('superpowers');
+        if (!installed)
+            return { agent: 'claude_code', state: 'missing' };
+        const marker = this.readMarker(baseDir);
+        const requestedRef = config?.ref;
+        if (marker && requestedRef && marker.ref !== requestedRef) {
+            return {
+                agent: 'claude_code',
+                state: 'drifted',
+                detail: `installed at ${marker.ref}, config requests ${requestedRef}`,
+            };
+        }
+        return {
+            agent: 'claude_code',
+            state: 'installed',
+            detail: marker ? `ref ${marker.ref}` : 'installed outside agentenv',
+        };
+    }
+    async detect(baseDir, config) {
+        const scope = resolveIntegrationScope({}, config);
+        const requestedAgents = config?.agents ?? [...AGENT_KEYS];
+        const result = {
+            name: this.getName(),
+            source: config?.source,
+            ref: config?.ref,
+            scope,
+            agents: [],
+            changedFiles: [],
+            nativeCommands: [],
+            warnings: [],
+            errors: [],
+        };
+        for (const agent of requestedAgents) {
+            if (agent !== 'claude_code') {
+                result.agents.push({ agent, state: 'unsupported', detail: MANUAL_INSTALL_HINTS[agent] });
+                continue;
+            }
+            result.agents.push(this.detectClaudeCode(baseDir, config));
+        }
+        return result;
+    }
+    async status(baseDir, config) {
+        return this.detect(baseDir, config);
+    }
+    async apply(baseDir, config) {
+        const detected = await this.detect(baseDir, config);
+        if (!this.isEnabled(config))
+            return detected;
+        const ref = config?.ref;
+        if (!ref || !config?.source) {
+            detected.errors.push('integrations.superpowers.source and .ref must be set to apply');
+            return detected;
+        }
+        for (const agentState of detected.agents) {
+            if (agentState.agent !== 'claude_code')
+                continue;
+            if (config.allow_hooks !== true) {
+                detected.warnings.push('Superpowers registers a SessionStart hook; set integrations.superpowers.allow_hooks = true to permit installing it for Claude Code.');
+                continue;
+            }
+            if (agentState.state === 'installed')
+                continue;
+            const wasDrifted = agentState.state === 'drifted';
+            const marketplaceArgs = [
+                'plugin',
+                'marketplace',
+                'add',
+                `${SUPERPOWERS_MARKETPLACE_REPO}#${ref}`,
+            ];
+            const marketplaceRun = this.runClaudeCli(marketplaceArgs, baseDir);
+            detected.nativeCommands.push(`claude ${marketplaceArgs.join(' ')}`);
+            if (!marketplaceRun.success) {
+                detected.errors.push(`claude plugin marketplace add failed: ${marketplaceRun.stderr || marketplaceRun.stdout}`);
+                continue;
+            }
+            const installArgs = ['plugin', 'install', SUPERPOWERS_PLUGIN_ID, '--scope', detected.scope];
+            const installRun = this.runClaudeCli(installArgs, baseDir);
+            detected.nativeCommands.push(`claude ${installArgs.join(' ')}`);
+            if (!installRun.success) {
+                detected.errors.push(`claude plugin install failed: ${installRun.stderr || installRun.stdout}`);
+                continue;
+            }
+            const marker = {
+                ref,
+                scope: detected.scope,
+                installedAt: new Date().toISOString(),
+            };
+            this.writeMarker(baseDir, marker);
+            detected.changedFiles.push(this.markerPath(baseDir));
+            agentState.state = 'installed';
+            agentState.detail = wasDrifted ? `updated to ref ${ref}` : `ref ${ref}`;
+        }
+        if (config.allow_external_requests !== true) {
+            detected.warnings.push('external requests disabled: agentenv never installs the optional Superpowers visual companion');
+        }
+        return detected;
+    }
+}
+//# sourceMappingURL=superpowers.js.map

package/dist/integrations/superpowers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"superpowers.js","sourceRoot":"","sources":["../../src/integrations/superpowers.ts"],"names":[],"mappings":"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"}

package/dist/shell/detector.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Tier 0 Shell Detection and Configuration
+ * Detects the shell environment and ensures POSIX compatibility on Windows
+ */
+import type { AgentKey } from '../config/schema.js';
+export declare const POSIX_UTILITIES: string[];
+export declare const GIT_BASH_PATHS: string[];
+export interface ShellInfo {
+    currentShell: string;
+    isPosixCompatible: boolean;
+    isWindows: boolean;
+    isMacOS: boolean;
+    isGitBash: boolean;
+    gitBashPath?: string;
+    gnubinPath?: string;
+    missingUtilities: string[];
+    pathEnvironment: string;
+}
+/**
+ * Detect the current shell environment
+ */
+export declare function detectShell(): ShellInfo;
+/**
+ * Install GNU coreutils on macOS via Homebrew.
+ * Returns the gnubin path that needs to be prepended to PATH, or undefined if installation fails.
+ */
+declare function installGNUCoreutilsMacOS(): string | undefined;
+/**
+ * Generate shell configuration for an agent
+ * Returns the shell configuration that should be used
+ */
+export declare function getShellConfiguration(shellInfo: ShellInfo): {
+    shell: string;
+    posixPath?: string;
+    gnuPath?: string;
+    needsConfiguration: boolean;
+};
+/**
+ * Generate PATH addition for Git Bash on Windows
+ */
+export declare function generateGitBashPathAddition(gitBashPath: string): string;
+/**
+ * Generate PATH addition for GNU coreutils on macOS
+ */
+export declare function generateMacOSGNUPathAddition(gnubinPath: string): string;
+export { installGNUCoreutilsMacOS };
+export type ShellFixAction = 'created' | 'updated' | 'unchanged' | 'skipped';
+export interface ShellFixResult {
+    agent: AgentKey;
+    file: string;
+    action: ShellFixAction;
+    message: string;
+}
+/**
+ * Resolve the full path to bash.exe from a detected Git Bash directory.
+ * Handles both the `usr\bin` form and the plain `bin` form Git for Windows ships.
+ * Uses win32 path semantics so the result is correct regardless of host OS
+ * (the tests exercise this on Linux CI).
+ */
+export declare function bashExecutable(gitBashPath: string): string;
+/**
+ * Apply the per-agent Tier 0 shell override for one agent, per
+ * docs/research/tier0-shell-fix.md:
+ * - claude_code: env.CLAUDE_CODE_GIT_BASH_PATH in ~/.claude/settings.json
+ * - codex_cli:   [windows] shell_path in ~/.codex/config.toml
+ * - opencode:    shell + defaultShell in ~/.config/opencode/opencode.json
+ * - copilot:     no per-file override exists (SHELL env var); skipped
+ *
+ * Existing user content is preserved; files are only written when a fix is
+ * actually needed, so repeated runs degrade to "unchanged".
+ */
+export declare function applyAgentShellFix(agent: AgentKey, bashExe: string, home: string): ShellFixResult;
+/**
+ * Fix shell configuration for Windows and macOS
+ * This is a Tier 0 fix - ensures POSIX utilities are available
+ */
+export declare function fixShellConfiguration(_baseDir?: string, agents?: AgentKey[]): {
+    success: boolean;
+    message: string;
+    gitBashPath?: string;
+    gnubinPath?: string;
+    results?: ShellFixResult[];
+};
+/**
+ * Check if a specific agent is configured to use a POSIX shell
+ */
+export declare function checkAgentShellConfiguration(agent: string): {
+    isConfigured: boolean;
+    shell?: string;
+    needsFix: boolean;
+};
+//# sourceMappingURL=detector.d.ts.map

package/dist/shell/detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detector.d.ts","sourceRoot":"","sources":["../../src/shell/detector.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAGpD,eAAO,MAAM,eAAe,UAgB3B,CAAC;AAGF,eAAO,MAAM,cAAc,UAK1B,CAAC;AAEF,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,SAAS,CAkFvC;AAqHD;;;GAGG;AACH,iBAAS,wBAAwB,IAAI,MAAM,GAAG,SAAS,CA6BtD;AA4BD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,SAAS,GAAG;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,OAAO,CAAC;CAC7B,CAkDA;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CASvE;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAMvE;AAGD,OAAO,EAAE,wBAAwB,EAAE,CAAC;AAEpC,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;AAE7E,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,QAAQ,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAS1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,cAAc,CAgBjG;AAoJD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,GAAE,MAAY,EACtB,MAAM,GAAE,QAAQ,EAAoB,GACnC;IACD,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;CAC5B,CAkFA;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,GAAG;IAC3D,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;CACnB,CAyBA"}