@phnx-labs/agents-cli 0.1.0

package/dist/lib/help.js

@@ -0,0 +1,63 @@
+function formatHelpCommandsFirst(cmd, helper) {
+    const termWidth = helper.padWidth(cmd, helper);
+    const helpWidth = helper.helpWidth || 80;
+    const itemIndentWidth = 2;
+    const itemSeparatorWidth = 2;
+    function formatItem(term, description) {
+        if (description) {
+            const fullText = `${term.padEnd(termWidth + itemSeparatorWidth)}${description}`;
+            return helper.wrap(fullText, helpWidth - itemIndentWidth, termWidth + itemSeparatorWidth);
+        }
+        return term;
+    }
+    function formatList(textArray) {
+        return textArray.join('\n').replace(/^/gm, ' '.repeat(itemIndentWidth));
+    }
+    let output = [`Usage: ${helper.commandUsage(cmd)}`, ''];
+    const commandDescription = helper.commandDescription(cmd);
+    if (commandDescription.length > 0) {
+        output = output.concat([helper.wrap(commandDescription, helpWidth, 0), '']);
+    }
+    const argumentList = helper.visibleArguments(cmd).map((argument) => {
+        return formatItem(helper.argumentTerm(argument), helper.argumentDescription(argument));
+    });
+    if (argumentList.length > 0) {
+        output = output.concat(['Arguments:', formatList(argumentList), '']);
+    }
+    const commandList = helper.visibleCommands(cmd).map((subcommand) => {
+        return formatItem(helper.subcommandTerm(subcommand), helper.subcommandDescription(subcommand));
+    });
+    if (commandList.length > 0) {
+        output = output.concat(['Commands:', formatList(commandList), '']);
+    }
+    const optionList = helper.visibleOptions(cmd).map((option) => {
+        return formatItem(helper.optionTerm(option), helper.optionDescription(option));
+    });
+    if (optionList.length > 0) {
+        output = output.concat(['Options:', formatList(optionList), '']);
+    }
+    if (helper.showGlobalOptions) {
+        const globalOptionList = helper.visibleGlobalOptions(cmd).map((option) => {
+            return formatItem(helper.optionTerm(option), helper.optionDescription(option));
+        });
+        if (globalOptionList.length > 0) {
+            output = output.concat(['Global Options:', formatList(globalOptionList), '']);
+        }
+    }
+    return output.join('\n');
+}
+function applyHelpConventionsRecursive(cmd) {
+    cmd
+        .helpOption('-h, --help', 'Show help')
+        .addHelpCommand(false)
+        .configureHelp({
+        formatHelp: formatHelpCommandsFirst,
+    });
+    for (const subcommand of cmd.commands) {
+        applyHelpConventionsRecursive(subcommand);
+    }
+}
+export function applyGlobalHelpConventions(root) {
+    applyHelpConventionsRecursive(root);
+}
+//# sourceMappingURL=help.js.map

package/dist/lib/help.js.map

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

package/dist/lib/hooks.d.ts

@@ -0,0 +1,116 @@
+import type { AgentId, InstalledHook, ManifestHook } from './types.js';
+export type HookEntry = {
+    name: string;
+    scriptPath: string;
+    dataFile?: string;
+};
+/**
+ * Check if a hook exists for an agent.
+ */
+export declare function hookExists(agentId: AgentId, hookName: string): boolean;
+/**
+ * Check if installed hook content matches source hook content.
+ * Compares both script file and data file (if present).
+ */
+export declare function hookContentMatches(agentId: AgentId, hookName: string, sourceEntry: HookEntry): boolean;
+export declare function listInstalledHooksWithScope(agentId: AgentId, cwd?: string, options?: {
+    home?: string;
+}): InstalledHook[];
+export declare function installHooks(source: string, agents: AgentId[], options?: {
+    scope?: 'user' | 'project';
+}): Promise<{
+    installed: string[];
+    errors: string[];
+}>;
+/**
+ * Path to the hooks dir of a specific version home (not the active one).
+ */
+export declare function getVersionHooksDir(agent: AgentId, version: string): string;
+/**
+ * List hook entries in a specific version home.
+ */
+export declare function listHooksInVersionHome(agent: AgentId, version: string): HookEntry[];
+export interface VersionHookDiff {
+    agent: AgentId;
+    version: string;
+    toAdd: string[];
+    toUpdate: string[];
+    matched: string[];
+    orphans: string[];
+}
+/**
+ * Compare a version home's hooks against central. Returns the reconciliation diff.
+ */
+export declare function diffVersionHooks(agent: AgentId, version: string): VersionHookDiff;
+/**
+ * Install a single hook from central into a specific version home.
+ */
+export declare function installHookToVersion(agent: AgentId, version: string, hookName: string): {
+    success: boolean;
+    error?: string;
+};
+/**
+ * Remove a single hook (script + data file) from a specific version home.
+ */
+export declare function removeHookFromVersion(agent: AgentId, version: string, hookName: string): {
+    success: boolean;
+    error?: string;
+};
+/**
+ * Iterate all (agent, version) pairs that support hooks and are installed,
+ * optionally scoped to a single agent/version.
+ */
+export declare function iterHooksCapableVersions(filter?: {
+    agent?: AgentId;
+    version?: string;
+}): Array<{
+    agent: AgentId;
+    version: string;
+}>;
+export declare function removeHook(name: string, agents: AgentId[]): Promise<{
+    removed: string[];
+    errors: string[];
+}>;
+/**
+ * Get detailed info about a hook from central storage.
+ */
+export declare function getHookInfo(name: string): {
+    name: string;
+    path: string;
+    content: string;
+} | null;
+export declare function discoverHooksFromRepo(repoPath: string): string[];
+/**
+ * Get the source hook entry from repo.
+ */
+export declare function getSourceHookEntry(repoPath: string, hookName: string): HookEntry | null;
+/**
+ * Install hooks to central ~/.agents/hooks/ directory.
+ * Shims will symlink this to per-agent directories for synced agents.
+ */
+export declare function installHooksCentrally(source: string): Promise<{
+    installed: string[];
+    errors: string[];
+}>;
+/**
+ * List hooks from central ~/.agents/hooks/ directory.
+ */
+export declare function listCentralHooks(): HookEntry[];
+/**
+ * Parse ~/.agents/hooks.yaml manifest.
+ * Returns hook definitions with lifecycle event metadata.
+ */
+export declare function parseHookManifest(): Record<string, ManifestHook>;
+/**
+ * Register hooks as lifecycle events in an agent's config.
+ * Reads hooks.yaml manifest, merges into the agent's config file(s).
+ * Only manages hooks whose command paths are under ~/.agents/hooks/.
+ * Does not remove user-added hooks.
+ *
+ * @param agentsDirOverride - Override the agents dir (used in tests to inject a temp path).
+ */
+export declare function registerHooksToSettings(agentId: AgentId, versionHome: string, hookManifest?: Record<string, ManifestHook>, agentsDirOverride?: string): {
+    registered: string[];
+    errors: string[];
+};
+//# sourceMappingURL=hooks.d.ts.map

package/dist/lib/hooks.d.ts.map

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