@alfe.ai/integrations 0.0.13 → 0.0.15

package/dist/index.d.ts

@@ -146,6 +146,7 @@ declare class InstallerError extends Error {
 }
 declare class Installer {
   private basePath;
+  private sharedPackagesReady;
   /**
    * @param basePath - Override the integrations directory (for testing).
    *                   Defaults to ~/.alfe/integrations/
@@ -159,6 +160,10 @@ declare class Installer {
    * Install an integration by cloning its git repo and checking out the pinned commit.
    * For monorepo integrations (with subdir), extracts only the subdir contents.
    *
+   * After cloning, ensures shared @alfe.ai packages are available at the root
+   * integrations directory, and runs `npm install --production` in the integration
+   * directory if it has its own package.json.
+   *
    * If the install path already exists (e.g. from a failed previous install),
    * it is cleaned up before retrying.
    */
@@ -180,6 +185,21 @@ declare class Installer {
    * Remove an installed integration.
    */
   remove(name: string): Promise<void>;
+  /**
+   * Ensure shared @alfe.ai packages are installed at the root integrations
+   * directory. Creates/updates a package.json and runs npm install.
+   *
+   * Node module resolution from hook scripts (e.g.
+   * ~/.alfe/integrations/console/hooks/post_install.js) walks up to
+   * ~/.alfe/integrations/node_modules/ and finds these packages.
+   */
+  private ensureSharedPackages;
+  /**
+   * Run `npm install --production` in an integration directory if it has
+   * its own package.json (for dependencies beyond the shared @alfe.ai packages).
+   */
+  private installLocalDependencies;
+  private runNpmInstall;
   /**
    * List all locally installed integrations.
    */
@@ -227,6 +247,18 @@ interface ConfigSchemaField {
   /** Only show this field if a specific integration is installed */
   depends_on_integration?: string;
 }
+interface CommandDeclaration {
+  /** Dot-namespaced command name (e.g. "support.diagnostic") */
+  name: string;
+  /** Relative path to handler file within integration directory */
+  handler: string;
+  /** Exported function name (default: "handle") */
+  method?: string;
+  /** Timeout in milliseconds (default: 30000) */
+  timeout_ms?: number;
+  /** Human-readable description */
+  description?: string;
+}
 interface SkillInstall {
   /** Relative path within the integration repo to the skill directory */
   path: string;
@@ -253,6 +285,7 @@ interface InstallTargets {
 interface IntegrationHooks {
   pre_install?: string;
   post_install?: string;
+  post_activate?: string;
   pre_uninstall?: string;
   post_uninstall?: string;
   health_check?: string;
@@ -290,6 +323,7 @@ interface IntegrationManifest {
   config_schema: ConfigSchemaField[];
   capabilities: string[];
   hooks: IntegrationHooks;
+  commands: CommandDeclaration[];
   /** Git repository URL (HTTPS) — not present in YAML, injected by the publish API */
   repository?: string;
   /**
@@ -480,6 +514,21 @@ declare class IntegrationManager {
    * Get a specific integration by name.
    */
   get(name: string): IntegrationInfo | undefined;
+  /**
+   * Get command declarations from all active integrations with resolved absolute paths.
+   * Used by the daemon to rebuild the command registry after reconciliation.
+   */
+  getActiveCommands(): {
+    integrationId: string;
+    commands: {
+      name: string;
+      handler: string;
+      resolvedPath: string;
+      method: string;
+      timeoutMs: number;
+      description?: string;
+    }[];
+  }[];
   /**
    * Clear in-memory secrets (called on daemon restart).
    */
@@ -537,8 +586,11 @@ declare class StateManager {
 /**
  * Hook Runner — executes integration lifecycle hook scripts.
  *
- * Hooks are shell scripts defined in the integration manifest.
- * They run as child processes with a 30-second timeout.
+ * Hooks are scripts defined in the integration manifest. The runner
+ * auto-detects the interpreter from the script's shebang line or file
+ * extension (.js/.mjs → node, .py → python3, default → bash).
+ *
+ * Scripts run as child processes with a 30-second timeout.
  * stdout/stderr are captured and returned.
  *
  * The runner injects standard environment variables:
@@ -575,9 +627,22 @@ interface HookEnvOptions {
  * - ALFE_<NAME_UPPER>_<KEY_UPPER>=value for each secret entry
  */
 declare function buildHookEnv(options: HookEnvOptions, additionalEnv?: Record<string, string>): Record<string, string>;
+/**
+ * Resolve the interpreter for a hook script by inspecting its shebang
+ * line or file extension.
+ *
+ * Priority:
+ * 1. Shebang line (e.g. #!/usr/bin/env node → "node")
+ * 2. File extension (.js/.mjs → "node", .py → "python3")
+ * 3. Default → "bash"
+ */
+
 /**
  * Run a hook script from an integration directory.
  *
+ * The interpreter is auto-detected from the script's shebang line or
+ * file extension. See {@link resolveInterpreter}.
+ *
  * @param integrationPath - Base path of the integration (where alfe-integration.yaml lives)
  * @param hookScript - Relative path to the hook script (e.g. "scripts/activate.sh")
  * @param env - Additional environment variables to pass to the script

package/dist/index.js

@@ -2,7 +2,7 @@ import { execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
 import { dirname, join } from "node:path";
 import { homedir, tmpdir } from "node:os";
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { buildConfigValidationSchema, parseManifestFile } from "@alfe.ai/integration-manifest";
 import { createLogger } from "@auriclabs/logger";
 //#region src/registry.ts
@@ -124,10 +124,22 @@ var Resolver = class {
 * Each integration is cloned and checked out to a pinned commit hash.
 * For monorepo integrations (with subdir), only the subdir contents
 * are extracted — the full clone is discarded.
+*
+* Shared @alfe.ai packages (@alfe.ai/config, @alfe.ai/agent-api-client)
+* are installed at the root integrations directory so all hook scripts
+* can resolve them via Node's upward module resolution.
 */
 const execFileAsync$1 = promisify(execFile);
+const log$1 = createLogger("Installer");
 const INTEGRATIONS_DIR = join(homedir(), ".alfe", "integrations");
 const GIT_TIMEOUT_MS = 6e4;
+const NPM_TIMEOUT_MS = 6e4;
+/** Shared @alfe.ai packages available to all integration hooks */
+const SHARED_PACKAGES = {
+	"@alfe.ai/config": "latest",
+	"@alfe.ai/agent-api-client": "latest",
+	"@alfe.ai/doctor": "latest"
+};
 var InstallerError = class extends Error {
 	constructor(message) {
 		super(message);
@@ -136,6 +148,7 @@ var InstallerError = class extends Error {
 };
 var Installer = class {
 	basePath;
+	sharedPackagesReady = false;
 	/**
 	* @param basePath - Override the integrations directory (for testing).
 	*                   Defaults to ~/.alfe/integrations/
@@ -153,6 +166,10 @@ var Installer = class {
 	* Install an integration by cloning its git repo and checking out the pinned commit.
 	* For monorepo integrations (with subdir), extracts only the subdir contents.
 	*
+	* After cloning, ensures shared @alfe.ai packages are available at the root
+	* integrations directory, and runs `npm install --production` in the integration
+	* directory if it has its own package.json.
+	*
 	* If the install path already exists (e.g. from a failed previous install),
 	* it is cleaned up before retrying.
 	*/
@@ -165,6 +182,8 @@ var Installer = class {
 		mkdirSync(this.basePath, { recursive: true });
 		if (resolved.subdir) await this.cloneAndExtractSubdir(resolved, installPath);
 		else await this.cloneDirect(resolved, installPath);
+		await this.ensureSharedPackages();
+		await this.installLocalDependencies(installPath);
 		return installPath;
 	}
 	/**
@@ -251,6 +270,66 @@ var Installer = class {
 		return Promise.resolve();
 	}
 	/**
+	* Ensure shared @alfe.ai packages are installed at the root integrations
+	* directory. Creates/updates a package.json and runs npm install.
+	*
+	* Node module resolution from hook scripts (e.g.
+	* ~/.alfe/integrations/console/hooks/post_install.js) walks up to
+	* ~/.alfe/integrations/node_modules/ and finds these packages.
+	*/
+	async ensureSharedPackages() {
+		if (this.sharedPackagesReady) return;
+		const pkgJsonPath = join(this.basePath, "package.json");
+		const nodeModulesExists = existsSync(join(this.basePath, "node_modules"));
+		let needsInstall = false;
+		if (existsSync(pkgJsonPath)) try {
+			const deps = JSON.parse(readFileSync(pkgJsonPath, "utf-8")).dependencies ?? {};
+			needsInstall = Object.keys(SHARED_PACKAGES).some((pkg) => !(pkg in deps));
+		} catch {
+			needsInstall = true;
+		}
+		else needsInstall = true;
+		if (!needsInstall && !nodeModulesExists) needsInstall = true;
+		if (!needsInstall) {
+			this.sharedPackagesReady = true;
+			return;
+		}
+		const pkgJson = {
+			name: "alfe-integrations-root",
+			private: true,
+			type: "module",
+			dependencies: { ...SHARED_PACKAGES }
+		};
+		writeFileSync(pkgJsonPath, JSON.stringify(pkgJson, null, 2) + "\n", "utf-8");
+		log$1.info("Installing shared @alfe.ai packages for integration hooks");
+		await this.runNpmInstall(this.basePath);
+		this.sharedPackagesReady = true;
+	}
+	/**
+	* Run `npm install --production` in an integration directory if it has
+	* its own package.json (for dependencies beyond the shared @alfe.ai packages).
+	*/
+	async installLocalDependencies(installPath) {
+		if (!existsSync(join(installPath, "package.json"))) return;
+		log$1.info({ path: installPath }, "Installing integration-specific npm dependencies");
+		await this.runNpmInstall(installPath);
+	}
+	async runNpmInstall(cwd) {
+		try {
+			await execFileAsync$1("npm", [
+				"install",
+				"--production",
+				"--no-audit",
+				"--no-fund"
+			], {
+				cwd,
+				timeout: NPM_TIMEOUT_MS
+			});
+		} catch (err) {
+			throw new InstallerError(`npm install failed in ${cwd}: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+	/**
 	* List all locally installed integrations.
 	*/
 	list() {
@@ -515,8 +594,11 @@ var LockManager = class {
 /**
 * Hook Runner — executes integration lifecycle hook scripts.
 *
-* Hooks are shell scripts defined in the integration manifest.
-* They run as child processes with a 30-second timeout.
+* Hooks are scripts defined in the integration manifest. The runner
+* auto-detects the interpreter from the script's shebang line or file
+* extension (.js/.mjs → node, .py → python3, default → bash).
+*
+* Scripts run as child processes with a 30-second timeout.
 * stdout/stderr are captured and returned.
 *
 * The runner injects standard environment variables:
@@ -571,8 +653,55 @@ function buildHookEnv(options, additionalEnv) {
 	return env;
 }
 /**
+* Resolve the interpreter for a hook script by inspecting its shebang
+* line or file extension.
+*
+* Priority:
+* 1. Shebang line (e.g. #!/usr/bin/env node → "node")
+* 2. File extension (.js/.mjs → "node", .py → "python3")
+* 3. Default → "bash"
+*/
+function resolveInterpreter(scriptPath) {
+	try {
+		const fd = openSync(scriptPath, "r");
+		const buf = Buffer.alloc(256);
+		readSync(fd, buf, 0, 256, 0);
+		closeSync(fd);
+		const firstLine = buf.toString("utf-8").split("\n")[0];
+		if (firstLine.startsWith("#!")) {
+			const shebang = firstLine.slice(2).trim();
+			if (shebang.startsWith("/usr/bin/env ")) {
+				const parts = shebang.slice(13).trim().split(/\s+/);
+				return {
+					command: parts[0],
+					args: [...parts.slice(1), scriptPath]
+				};
+			}
+			return {
+				command: shebang.split(/\s+/)[0],
+				args: [scriptPath]
+			};
+		}
+	} catch {}
+	if (scriptPath.endsWith(".js") || scriptPath.endsWith(".mjs")) return {
+		command: "node",
+		args: [scriptPath]
+	};
+	if (scriptPath.endsWith(".py")) return {
+		command: "python3",
+		args: [scriptPath]
+	};
+	return {
+		command: "bash",
+		args: [scriptPath]
+	};
+}
+/**
 * Run a hook script from an integration directory.
 *
+* The interpreter is auto-detected from the script's shebang line or
+* file extension. See {@link resolveInterpreter}.
+*
 * @param integrationPath - Base path of the integration (where alfe-integration.yaml lives)
 * @param hookScript - Relative path to the hook script (e.g. "scripts/activate.sh")
 * @param env - Additional environment variables to pass to the script
@@ -586,11 +715,12 @@ async function runHook(integrationPath, hookScript, env) {
 		stderr: `Hook script not found: ${scriptPath} (skipped)`,
 		timedOut: false
 	};
+	const { command, args } = resolveInterpreter(scriptPath);
 	return new Promise((resolve) => {
 		let stdout = "";
 		let stderr = "";
 		let timedOut = false;
-		const proc = spawn("bash", [scriptPath], {
+		const proc = spawn(command, args, {
 			cwd: integrationPath,
 			env: {
 				...process.env,
@@ -757,7 +887,7 @@ var IntegrationManager = class {
 					config: config ?? {},
 					secrets: this.secrets.get(name)
 				});
-				if (hookResult.exitCode !== 0) this.log.warn(`post_install hook failed (non-fatal): ${hookResult.stderr || hookResult.stdout}`);
+				if (hookResult.exitCode !== 0) throw new Error(`post_install hook failed (exit ${String(hookResult.exitCode)}): ${hookResult.stderr || hookResult.stdout}`);
 			}
 			this.state.set(name, {
 				status: "installed",
@@ -894,6 +1024,18 @@ var IntegrationManager = class {
 				if (plugins.length > 0 || skills.length > 0) this.lockManager.addEntries(runtimeName, integrationId, manifest.version, plugins, skills, installPath);
 			}
 			this.state.setStatus(integrationId, "active");
+			if (manifest.hooks.post_activate) {
+				this.log.info(`Running post_activate hook: ${manifest.hooks.post_activate}`);
+				const hookResult = await runHookWithContext(installPath, manifest.hooks.post_activate, {
+					integrationName: integrationId,
+					config: entry.config,
+					secrets: this.secrets.get(integrationId)
+				});
+				if (hookResult.exitCode !== 0) {
+					this.state.setStatus(integrationId, "error", `post_activate hook failed: ${hookResult.stderr || hookResult.stdout}`);
+					return this.err("POST_ACTIVATE_FAILED", `post_activate hook failed (exit ${String(hookResult.exitCode)}): ${hookResult.stderr || hookResult.stdout}`);
+				}
+			}
 			if (manifest.hooks.health_check) {
 				this.log.info(`Running health check: ${manifest.hooks.health_check}`);
 				const hookResult = await runHookWithContext(installPath, manifest.hooks.health_check, {
@@ -1106,6 +1248,37 @@ var IntegrationManager = class {
 		};
 	}
 	/**
+	* Get command declarations from all active integrations with resolved absolute paths.
+	* Used by the daemon to rebuild the command registry after reconciliation.
+	*/
+	getActiveCommands() {
+		const result = [];
+		for (const entry of this.state.list()) {
+			if (entry.status !== "active") continue;
+			const installPath = this.installer.getInstallPath(entry.id);
+			const manifestPath = join(installPath, "alfe-integration.yaml");
+			if (!existsSync(manifestPath)) continue;
+			try {
+				const manifest = parseManifestFile(manifestPath);
+				if (manifest.commands.length === 0) continue;
+				result.push({
+					integrationId: entry.id,
+					commands: manifest.commands.map((cmd) => ({
+						name: cmd.name,
+						handler: cmd.handler,
+						resolvedPath: join(installPath, cmd.handler),
+						method: cmd.method ?? "handle",
+						timeoutMs: cmd.timeout_ms ?? 3e4,
+						description: cmd.description
+					}))
+				});
+			} catch (err) {
+				this.log.warn(`Failed to read commands for "${entry.id}": ${err instanceof Error ? err.message : String(err)}`);
+			}
+		}
+		return result;
+	}
+	/**
 	* Clear in-memory secrets (called on daemon restart).
 	*/
 	clear() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/integrations",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "Integration lifecycle management for Alfe — registry, resolution, installation, and state",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,7 +13,7 @@
   },
   "dependencies": {
     "@auriclabs/logger": "^0.1.1",
-    "@alfe.ai/integration-manifest": "^0.0.4"
+    "@alfe.ai/integration-manifest": "^0.0.6"
   },
   "files": [
     "dist"