aem-ext-daemon 0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# aem-ext-daemon
+
+Local daemon for **AEM Extension Builder**. Connects your machine to the cloud UI so the builder can scaffold extensions, run CLI commands, and manage files on your local filesystem.
+
+## Quick Start
+
+```bash
+npx aem-ext-daemon
+```
+
+That's it. On first run the daemon will display a QR code and pairing URL. Open it in your browser to connect.
+
+## How It Works
+
+1. The daemon runs on your machine and connects outbound to the cloud app via WebSocket
+2. On first run, it generates a unique identity and a pairing code
+3. You scan the QR code (or open the URL) in your browser to link the daemon to your session
+4. Once paired, the cloud UI can send commands (file operations, git, AIO CLI) that execute locally
+5. On subsequent starts, the daemon reconnects automatically — no re-pairing needed
+
+## Options
+
+```
+npx aem-ext-daemon [options]
+
+  --server <url>       Cloud app URL (uses default if omitted)
+  --workspace <path>   Set the workspace root directory
+  --reset              Clear identity and force re-pairing
+  --help, -h           Show help
+  --version, -v        Show version
+```
+
+## Prerequisites
+
+- **Node.js 18+**
+- **AIO CLI** (optional, for extension scaffolding): `npm install -g @adobe/aio-cli`
+
+## Config Location
+
+- **macOS/Linux**: `~/.config/aem-ext-daemon/config.json`
+- **Windows**: `%APPDATA%\aem-ext-daemon\config.json`
+
+## Security
+
+- The daemon only executes commands within the configured workspace directory
+- All paths are validated to prevent traversal outside the workspace
+- Communication uses WSS (TLS-encrypted WebSocket)
+- Identity is verified with a 256-bit secret hashed server-side

package/bin/cli.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for aem-ext-daemon.
+ *
+ * Usage:
+ *   npx aem-ext-daemon                              # connect to default server
+ *   npx aem-ext-daemon --server https://my.app.com  # custom server
+ *   npx aem-ext-daemon --workspace /path/to/projects # set workspace
+ *   npx aem-ext-daemon --reset                       # clear identity and re-pair
+ */
+
+import { Daemon } from "../dist/daemon.js";
+import { resetIdentity, getConfigPath, getRailwayUrl } from "../dist/identity.js";
+
+const DEFAULT_SERVER = "https://adobe-extension-builder-production.up.railway.app";
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--server" && argv[i + 1]) {
+      args.server = argv[++i];
+    } else if (arg === "--workspace" && argv[i + 1]) {
+      args.workspace = argv[++i];
+    } else if (arg === "--reset") {
+      args.reset = true;
+    } else if (arg === "--help" || arg === "-h") {
+      args.help = true;
+    } else if (arg === "--version" || arg === "-v") {
+      args.version = true;
+    }
+  }
+  return args;
+}
+
+function printHelp() {
+  console.log(`
+  aem-ext-daemon — Local daemon for AEM Extension Builder
+
+  Usage:
+    npx aem-ext-daemon [options]
+
+  Options:
+    --server <url>       Cloud app URL (default: Railway production)
+    --workspace <path>   Set the workspace root directory
+    --reset              Clear identity and force re-pairing
+    --help, -h           Show this help message
+    --version, -v        Show version
+
+  Config location:
+    ${getConfigPath()}
+  `);
+}
+
+const args = parseArgs(process.argv);
+
+if (args.help) {
+  printHelp();
+  process.exit(0);
+}
+
+if (args.version) {
+  console.log("0.1.0");
+  process.exit(0);
+}
+
+if (args.reset) {
+  resetIdentity();
+  console.log("  ✓  Identity reset. Will re-pair on next connection.");
+  console.log("");
+}
+
+// Resolve server URL: CLI flag > saved config > default
+const serverUrl = args.server || getRailwayUrl() || DEFAULT_SERVER;
+
+const daemon = new Daemon({
+  serverUrl,
+  workspace: args.workspace,
+});
+
+// Graceful shutdown
+process.on("SIGINT", () => {
+  daemon.stop();
+  process.exit(0);
+});
+
+process.on("SIGTERM", () => {
+  daemon.stop();
+  process.exit(0);
+});
+
+daemon.start();

package/dist/capabilities/fs.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Filesystem capabilities — browse, read, write, list.
+ */
+export interface BrowseEntry {
+    name: string;
+    path: string;
+    isDirectory: boolean;
+    isHidden: boolean;
+}
+/** Browse a directory — returns immediate children with metadata. */
+export declare function browse(dirPath: string, showHidden?: boolean): string;
+/** Read a file and return its content. */
+export declare function readFile(filePath: string): string;
+/** Write content to a file. Creates parent directories if needed. */
+export declare function writeFile(filePath: string, content: string): string;
+/** Recursive directory listing up to a max depth. */
+export declare function listRecursive(dirPath: string, maxDepth?: number): string;

package/dist/capabilities/fs.js

@@ -0,0 +1,78 @@
+/**
+ * Filesystem capabilities — browse, read, write, list.
+ */
+import fs from "node:fs";
+import path from "node:path";
+/** Browse a directory — returns immediate children with metadata. */
+export function browse(dirPath, showHidden = false) {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    const result = entries
+        .filter((e) => showHidden || !e.name.startsWith("."))
+        .map((e) => ({
+        name: e.name,
+        path: path.join(dirPath, e.name),
+        isDirectory: e.isDirectory(),
+        isHidden: e.name.startsWith("."),
+    }))
+        .sort((a, b) => {
+        // Directories first, then alphabetical
+        if (a.isDirectory && !b.isDirectory)
+            return -1;
+        if (!a.isDirectory && b.isDirectory)
+            return 1;
+        return a.name.localeCompare(b.name);
+    });
+    return JSON.stringify(result);
+}
+/** Read a file and return its content. */
+export function readFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+    const stat = fs.statSync(filePath);
+    if (stat.size > 2 * 1024 * 1024) {
+        throw new Error(`File too large (${stat.size} bytes). Max 2MB.`);
+    }
+    return fs.readFileSync(filePath, "utf-8");
+}
+/** Write content to a file. Creates parent directories if needed. */
+export function writeFile(filePath, content) {
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(filePath, content, "utf-8");
+    return `Written ${content.length} bytes to ${filePath}`;
+}
+/** Recursive directory listing up to a max depth. */
+export function listRecursive(dirPath, maxDepth = 3) {
+    const result = [];
+    function walk(dir, prefix, depth) {
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        // Filter out common noise
+        const filtered = entries.filter((e) => !e.name.startsWith(".") &&
+            e.name !== "node_modules" &&
+            e.name !== "__pycache__" &&
+            e.name !== "dist" &&
+            e.name !== ".git");
+        for (let i = 0; i < filtered.length; i++) {
+            const entry = filtered[i];
+            const isLast = i === filtered.length - 1;
+            const connector = isLast ? "└── " : "├── ";
+            const childPrefix = isLast ? "    " : "│   ";
+            result.push(`${prefix}${connector}${entry.name}${entry.isDirectory() ? "/" : ""}`);
+            if (entry.isDirectory()) {
+                walk(path.join(dir, entry.name), prefix + childPrefix, depth + 1);
+            }
+        }
+    }
+    result.push(path.basename(dirPath) + "/");
+    walk(dirPath, "", 0);
+    return result.join("\n");
+}

package/dist/capabilities/git.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Git capabilities — clone, status.
+ * Uses child_process to avoid heavy dependencies.
+ */
+/** Clone a repository into a destination directory. */
+export declare function clone(url: string, dest: string, branch?: string): string;
+/** Get git status of a directory. */
+export declare function status(dir: string): string;

package/dist/capabilities/git.js

@@ -0,0 +1,41 @@
+/**
+ * Git capabilities — clone, status.
+ * Uses child_process to avoid heavy dependencies.
+ */
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+/** Clone a repository into a destination directory. */
+export function clone(url, dest, branch) {
+    if (!url)
+        throw new Error("url is required");
+    if (!dest)
+        throw new Error("dest is required");
+    const args = ["git", "clone"];
+    if (branch)
+        args.push("--branch", branch);
+    args.push("--depth", "1", url, dest);
+    execSync(args.join(" "), {
+        timeout: 120_000,
+        maxBuffer: 10 * 1024 * 1024,
+        stdio: "pipe",
+    });
+    return `Cloned ${url} into ${dest}`;
+}
+/** Get git status of a directory. */
+export function status(dir) {
+    if (!fs.existsSync(dir)) {
+        throw new Error(`Directory not found: ${dir}`);
+    }
+    try {
+        const result = execSync("git status --porcelain -b", {
+            cwd: dir,
+            timeout: 10_000,
+            maxBuffer: 1024 * 1024,
+            encoding: "utf-8",
+        });
+        return result || "Clean working tree";
+    }
+    catch {
+        throw new Error(`Not a git repository: ${dir}`);
+    }
+}

package/dist/capabilities/shell.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shell capabilities — execute commands, run AIO CLI.
+ *
+ * aio:run streams stdout/stderr back through the WebSocket.
+ * shell:exec runs a command and returns the full output.
+ */
+import type { DaemonConnection } from "../connection.js";
+/** Run a shell command synchronously and return stdout. */
+export declare function exec(command: string, cwd: string): string;
+/** Check if AIO CLI is installed and return its version. */
+export declare function checkAio(): string;
+/**
+ * Run an AIO CLI command with streaming output.
+ * Streams stdout/stderr chunks back through the WebSocket,
+ * then returns the exit code.
+ */
+export declare function runAio(args: string[], cwd: string, requestId: string, connection: DaemonConnection): Promise<string>;

package/dist/capabilities/shell.js

@@ -0,0 +1,96 @@
+/**
+ * Shell capabilities — execute commands, run AIO CLI.
+ *
+ * aio:run streams stdout/stderr back through the WebSocket.
+ * shell:exec runs a command and returns the full output.
+ */
+import { execSync, spawn } from "node:child_process";
+const EXEC_TIMEOUT = 120_000; // 2 minutes
+const MAX_BUFFER = 5 * 1024 * 1024; // 5MB
+/** Run a shell command synchronously and return stdout. */
+export function exec(command, cwd) {
+    if (!command)
+        throw new Error("command is required");
+    const result = execSync(command, {
+        cwd,
+        timeout: EXEC_TIMEOUT,
+        maxBuffer: MAX_BUFFER,
+        encoding: "utf-8",
+        shell: "/bin/sh",
+    });
+    return result;
+}
+/** Check if AIO CLI is installed and return its version. */
+export function checkAio() {
+    try {
+        const version = execSync("aio --version", {
+            timeout: 10_000,
+            encoding: "utf-8",
+            shell: "/bin/sh",
+        }).trim();
+        return JSON.stringify({ installed: true, version });
+    }
+    catch {
+        return JSON.stringify({
+            installed: false,
+            error: "aio CLI not found. Install it: npm install -g @adobe/aio-cli",
+        });
+    }
+}
+/**
+ * Run an AIO CLI command with streaming output.
+ * Streams stdout/stderr chunks back through the WebSocket,
+ * then returns the exit code.
+ */
+export function runAio(args, cwd, requestId, connection) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("aio", args, {
+            cwd,
+            shell: true,
+            env: { ...process.env },
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (chunk) => {
+            const data = chunk.toString();
+            stdout += data;
+            connection.send({
+                type: "stream",
+                id: requestId,
+                channel: "stdout",
+                data,
+            });
+        });
+        child.stderr?.on("data", (chunk) => {
+            const data = chunk.toString();
+            stderr += data;
+            connection.send({
+                type: "stream",
+                id: requestId,
+                channel: "stderr",
+                data,
+            });
+        });
+        child.on("close", (exitCode) => {
+            connection.send({
+                type: "stream_done",
+                id: requestId,
+                exitCode: exitCode ?? 1,
+            });
+            if (exitCode === 0) {
+                resolve(stdout || "Command completed successfully");
+            }
+            else {
+                reject(new Error(stderr || `aio exited with code ${exitCode}`));
+            }
+        });
+        child.on("error", (err) => {
+            reject(new Error(`Failed to spawn aio: ${err.message}`));
+        });
+        // Timeout after 5 minutes
+        setTimeout(() => {
+            child.kill("SIGTERM");
+            reject(new Error("aio command timed out after 5 minutes"));
+        }, 300_000);
+    });
+}

package/dist/connection.d.ts

@@ -0,0 +1,37 @@
+/**
+ * WebSocket connection manager with auto-reconnect.
+ *
+ * Connects outbound to Railway — no tunnels or port-forwarding needed.
+ * Uses exponential backoff for reconnection.
+ */
+import type { DaemonOutbound, RailwayOutbound } from "./protocol.js";
+export type MessageHandler = (msg: RailwayOutbound) => void;
+export type StatusHandler = (status: "connecting" | "connected" | "disconnected") => void;
+interface ConnectionOptions {
+    url: string;
+    onMessage: MessageHandler;
+    onStatus: StatusHandler;
+}
+export declare class DaemonConnection {
+    private ws;
+    private url;
+    private onMessage;
+    private onStatus;
+    private backoff;
+    private reconnectTimer;
+    private pingTimer;
+    private intentionalClose;
+    constructor(opts: ConnectionOptions);
+    /** Initiate the WebSocket connection. */
+    connect(): void;
+    /** Send a message to Railway. */
+    send(msg: DaemonOutbound): void;
+    /** Gracefully disconnect. */
+    disconnect(): void;
+    get isConnected(): boolean;
+    private startPing;
+    private stopPing;
+    private scheduleReconnect;
+    private cleanup;
+}
+export {};

package/dist/connection.js

@@ -0,0 +1,113 @@
+/**
+ * WebSocket connection manager with auto-reconnect.
+ *
+ * Connects outbound to Railway — no tunnels or port-forwarding needed.
+ * Uses exponential backoff for reconnection.
+ */
+import WebSocket from "ws";
+import { encode, decode } from "./protocol.js";
+const MIN_BACKOFF = 1000; // 1 second
+const MAX_BACKOFF = 30000; // 30 seconds
+const PING_INTERVAL = 25000; // 25 seconds (keep-alive)
+export class DaemonConnection {
+    ws = null;
+    url;
+    onMessage;
+    onStatus;
+    backoff = MIN_BACKOFF;
+    reconnectTimer = null;
+    pingTimer = null;
+    intentionalClose = false;
+    constructor(opts) {
+        this.url = opts.url;
+        this.onMessage = opts.onMessage;
+        this.onStatus = opts.onStatus;
+    }
+    /** Initiate the WebSocket connection. */
+    connect() {
+        this.intentionalClose = false;
+        this.onStatus("connecting");
+        try {
+            this.ws = new WebSocket(this.url);
+        }
+        catch {
+            this.scheduleReconnect();
+            return;
+        }
+        this.ws.on("open", () => {
+            this.backoff = MIN_BACKOFF;
+            this.onStatus("connected");
+            this.startPing();
+        });
+        this.ws.on("message", (data) => {
+            try {
+                const msg = decode(data.toString());
+                if (msg.type === "ping") {
+                    this.send({ type: "pong" });
+                    return;
+                }
+                this.onMessage(msg);
+            }
+            catch {
+                // ignore malformed messages
+            }
+        });
+        this.ws.on("close", () => {
+            this.cleanup();
+            this.onStatus("disconnected");
+            if (!this.intentionalClose) {
+                this.scheduleReconnect();
+            }
+        });
+        this.ws.on("error", () => {
+            // error always followed by close, handled there
+        });
+    }
+    /** Send a message to Railway. */
+    send(msg) {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(encode(msg));
+        }
+    }
+    /** Gracefully disconnect. */
+    disconnect() {
+        this.intentionalClose = true;
+        this.cleanup();
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+    }
+    get isConnected() {
+        return this.ws?.readyState === WebSocket.OPEN;
+    }
+    startPing() {
+        this.stopPing();
+        this.pingTimer = setInterval(() => {
+            this.send({ type: "pong" }); // heartbeat
+        }, PING_INTERVAL);
+    }
+    stopPing() {
+        if (this.pingTimer) {
+            clearInterval(this.pingTimer);
+            this.pingTimer = null;
+        }
+    }
+    scheduleReconnect() {
+        if (this.intentionalClose)
+            return;
+        const jitter = Math.random() * 500;
+        const delay = Math.min(this.backoff + jitter, MAX_BACKOFF);
+        this.reconnectTimer = setTimeout(() => {
+            this.backoff = Math.min(this.backoff * 2, MAX_BACKOFF);
+            this.connect();
+        }, delay);
+    }
+    cleanup() {
+        this.stopPing();
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+}

package/dist/daemon.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Main daemon process.
+ *
+ * Lifecycle:
+ *   1. Load/generate identity
+ *   2. Connect to Railway WebSocket
+ *   3. Send register message
+ *   4. Handle needs_pairing → generate code, display QR
+ *   5. Handle paired/reconnected → ready for commands
+ *   6. Dispatch incoming tool_exec messages to capabilities
+ */
+export interface DaemonOptions {
+    serverUrl: string;
+    workspace?: string;
+}
+export declare class Daemon {
+    private connection;
+    private identity;
+    private serverUrl;
+    private pairCode;
+    constructor(opts: DaemonOptions);
+    /** Start the daemon. */
+    start(): void;
+    /** Stop the daemon gracefully. */
+    stop(): void;
+    private handleStatus;
+    private handleMessage;
+    private handleNeedsPairing;
+    private handlePaired;
+    private handleReconnected;
+    private handleToolExec;
+}

package/dist/daemon.js

@@ -0,0 +1,158 @@
+/**
+ * Main daemon process.
+ *
+ * Lifecycle:
+ *   1. Load/generate identity
+ *   2. Connect to Railway WebSocket
+ *   3. Send register message
+ *   4. Handle needs_pairing → generate code, display QR
+ *   5. Handle paired/reconnected → ready for commands
+ *   6. Dispatch incoming tool_exec messages to capabilities
+ */
+import os from "node:os";
+import { DaemonConnection } from "./connection.js";
+import { ensureIdentity, getWorkspaceRoot, setWorkspaceRoot } from "./identity.js";
+import { generatePairCode, displayPairCode } from "./pairing.js";
+import { dispatch } from "./dispatcher.js";
+const VERSION = "0.1.0";
+export class Daemon {
+    connection;
+    identity;
+    serverUrl;
+    pairCode = null;
+    constructor(opts) {
+        this.serverUrl = opts.serverUrl.replace(/\/$/, "");
+        this.identity = ensureIdentity();
+        if (opts.workspace) {
+            setWorkspaceRoot(opts.workspace);
+        }
+        // Build the WebSocket URL
+        const wsBase = this.serverUrl
+            .replace(/^https:/, "wss:")
+            .replace(/^http:/, "ws:");
+        const wsUrl = `${wsBase}/api/daemon/ws`;
+        this.connection = new DaemonConnection({
+            url: wsUrl,
+            onMessage: this.handleMessage.bind(this),
+            onStatus: this.handleStatus.bind(this),
+        });
+    }
+    /** Start the daemon. */
+    start() {
+        console.log("");
+        console.log("  ┌─────────────────────────────────────┐");
+        console.log("  │  AEM Extension Builder — Daemon      │");
+        console.log("  │  v" + VERSION.padEnd(35) + "│");
+        console.log("  └─────────────────────────────────────┘");
+        console.log("");
+        console.log(`  Daemon ID:  ${this.identity.daemonId.slice(0, 12)}...`);
+        console.log(`  Server:     ${this.serverUrl}`);
+        const workspace = getWorkspaceRoot();
+        if (workspace) {
+            console.log(`  Workspace:  ${workspace}`);
+        }
+        console.log("");
+        console.log("  Connecting...");
+        this.connection.connect();
+    }
+    /** Stop the daemon gracefully. */
+    stop() {
+        console.log("\n  Shutting down...");
+        this.connection.disconnect();
+    }
+    handleStatus(status) {
+        switch (status) {
+            case "connecting":
+                // quiet — initial connecting logged in start()
+                break;
+            case "connected":
+                // Send register message
+                this.connection.send({
+                    type: "register",
+                    daemonId: this.identity.daemonId,
+                    secret: this.identity.secret,
+                    version: VERSION,
+                    platform: `${os.platform()}-${os.arch()}`,
+                    workspaceRoot: getWorkspaceRoot(),
+                });
+                break;
+            case "disconnected":
+                console.log("  ⚠  Disconnected — will retry...");
+                break;
+        }
+    }
+    handleMessage(msg) {
+        switch (msg.type) {
+            case "needs_pairing":
+                this.handleNeedsPairing();
+                break;
+            case "paired":
+                this.handlePaired(msg.appUrl);
+                break;
+            case "reconnected":
+                this.handleReconnected(msg.appUrl);
+                break;
+            case "tool_exec":
+                this.handleToolExec(msg.id, msg.command, msg.payload);
+                break;
+            case "error":
+                console.error(`  ✗  Server error: ${msg.message}`);
+                break;
+            default:
+                // Unknown message type — ignore
+                break;
+        }
+    }
+    handleNeedsPairing() {
+        this.pairCode = generatePairCode();
+        // Send pair code to Railway
+        this.connection.send({
+            type: "pair_code",
+            code: this.pairCode,
+        });
+        // Display to user
+        const pairUrl = `${this.serverUrl}/pair?code=${this.pairCode}`;
+        console.log("");
+        console.log("  ╔═══════════════════════════════════════╗");
+        console.log("  ║         PAIR WITH YOUR BROWSER        ║");
+        console.log("  ╚═══════════════════════════════════════╝");
+        console.log("");
+        console.log(`  Code:  ${this.pairCode}`);
+        console.log("");
+        console.log(`  Open:  ${pairUrl}`);
+        console.log("");
+        displayPairCode(pairUrl);
+        console.log("");
+        console.log("  Waiting for browser to confirm...");
+    }
+    handlePaired(appUrl) {
+        this.pairCode = null;
+        console.log("");
+        console.log("  ✓  Paired — ready");
+        console.log(`  ✓  Open ${appUrl} in your browser`);
+        console.log("");
+    }
+    handleReconnected(appUrl) {
+        console.log("  ✓  Reconnected — ready");
+        console.log(`  ✓  ${appUrl}`);
+        console.log("");
+    }
+    async handleToolExec(id, command, payload) {
+        try {
+            const result = await dispatch(command, payload, this.connection);
+            this.connection.send({
+                type: "tool_result",
+                id,
+                result: typeof result === "string" ? result : JSON.stringify(result),
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : "Unknown error";
+            this.connection.send({
+                type: "tool_result",
+                id,
+                error: message,
+            });
+        }
+    }
+}

package/dist/dispatcher.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Command dispatcher — routes incoming tool_exec commands to capability handlers.
+ *
+ * Each command maps to a capability module. All path arguments are validated
+ * to be within the configured workspace root.
+ */
+import type { DaemonConnection } from "./connection.js";
+/**
+ * Dispatch a command to the appropriate capability handler.
+ */
+export declare function dispatch(command: string, payload: Record<string, unknown>, connection: DaemonConnection): Promise<string | Record<string, unknown>>;

package/dist/dispatcher.js

@@ -0,0 +1,92 @@
+/**
+ * Command dispatcher — routes incoming tool_exec commands to capability handlers.
+ *
+ * Each command maps to a capability module. All path arguments are validated
+ * to be within the configured workspace root.
+ */
+import path from "node:path";
+import { getWorkspaceRoot, setWorkspaceRoot } from "./identity.js";
+import * as fsCap from "./capabilities/fs.js";
+import * as gitCap from "./capabilities/git.js";
+import * as shellCap from "./capabilities/shell.js";
+/**
+ * Validate that a given path is within the workspace root.
+ * Prevents path traversal attacks.
+ */
+function validatePath(targetPath) {
+    const workspace = getWorkspaceRoot();
+    if (!workspace) {
+        throw new Error("No workspace root configured. Set one via the UI or --workspace flag.");
+    }
+    const resolved = path.resolve(workspace, targetPath);
+    if (!resolved.startsWith(path.resolve(workspace))) {
+        throw new Error(`Path "${targetPath}" is outside the workspace root.`);
+    }
+    return resolved;
+}
+/**
+ * Dispatch a command to the appropriate capability handler.
+ */
+export async function dispatch(command, payload, connection) {
+    switch (command) {
+        // ─── Filesystem ─────────────────────────────────────
+        case "fs:browse": {
+            const target = payload.path
+                ? validatePath(payload.path)
+                : getWorkspaceRoot();
+            return fsCap.browse(target, payload.showHidden);
+        }
+        case "fs:read": {
+            const filePath = validatePath(payload.path);
+            return fsCap.readFile(filePath);
+        }
+        case "fs:write": {
+            const filePath = validatePath(payload.path);
+            return fsCap.writeFile(filePath, payload.content);
+        }
+        case "fs:list": {
+            const target = payload.path
+                ? validatePath(payload.path)
+                : getWorkspaceRoot();
+            return fsCap.listRecursive(target, payload.depth);
+        }
+        // ─── Workspace ──────────────────────────────────────
+        case "workspace:get": {
+            return { workspaceRoot: getWorkspaceRoot() };
+        }
+        case "workspace:set": {
+            const newPath = payload.path;
+            if (!newPath)
+                throw new Error("path is required");
+            setWorkspaceRoot(newPath);
+            return { workspaceRoot: newPath };
+        }
+        // ─── Git ────────────────────────────────────────────
+        case "git:clone": {
+            const dest = validatePath(payload.dest);
+            return gitCap.clone(payload.url, dest, payload.branch);
+        }
+        case "git:status": {
+            const dir = validatePath(payload.path);
+            return gitCap.status(dir);
+        }
+        // ─── Shell / AIO CLI ────────────────────────────────
+        case "aio:run": {
+            const cwd = payload.cwd
+                ? validatePath(payload.cwd)
+                : getWorkspaceRoot();
+            return shellCap.runAio(payload.args, cwd, payload.id, connection);
+        }
+        case "aio:check": {
+            return shellCap.checkAio();
+        }
+        case "shell:exec": {
+            const cwd = payload.cwd
+                ? validatePath(payload.cwd)
+                : getWorkspaceRoot();
+            return shellCap.exec(payload.command, cwd);
+        }
+        default:
+            throw new Error(`Unknown command: ${command}`);
+    }
+}

package/dist/identity.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Identity module — generates and persists a unique daemon identity.
+ *
+ * Stored at:
+ *   macOS/Linux: ~/.config/aem-ext-daemon/config.json
+ *   Windows:     %APPDATA%\aem-ext-daemon\config.json
+ *
+ * Fields:
+ *   daemonId      — 128-bit hex, generated once, never changes
+ *   secret        — 256-bit hex, generated once, sent on every connection
+ *   workspaceRoot — user-selected workspace path (set after first pairing)
+ *   railwayUrl    — WebSocket URL for the Railway app
+ */
+export interface DaemonConfig {
+    daemonId: string;
+    secret: string;
+    workspaceRoot: string;
+    railwayUrl: string;
+}
+/** Ensure daemonId and secret exist; generate if missing. */
+export declare function ensureIdentity(): {
+    daemonId: string;
+    secret: string;
+};
+export declare function getWorkspaceRoot(): string;
+export declare function setWorkspaceRoot(path: string): void;
+export declare function getRailwayUrl(): string;
+export declare function setRailwayUrl(url: string): void;
+export declare function getConfigPath(): string;
+export declare function getAllConfig(): DaemonConfig;
+/** Reset identity — used for testing or "unpair" flow. */
+export declare function resetIdentity(): void;

package/dist/identity.js

@@ -0,0 +1,65 @@
+/**
+ * Identity module — generates and persists a unique daemon identity.
+ *
+ * Stored at:
+ *   macOS/Linux: ~/.config/aem-ext-daemon/config.json
+ *   Windows:     %APPDATA%\aem-ext-daemon\config.json
+ *
+ * Fields:
+ *   daemonId      — 128-bit hex, generated once, never changes
+ *   secret        — 256-bit hex, generated once, sent on every connection
+ *   workspaceRoot — user-selected workspace path (set after first pairing)
+ *   railwayUrl    — WebSocket URL for the Railway app
+ */
+import Conf from "conf";
+import crypto from "node:crypto";
+const store = new Conf({
+    projectName: "aem-ext-daemon",
+    schema: {
+        daemonId: { type: "string", default: "" },
+        secret: { type: "string", default: "" },
+        workspaceRoot: { type: "string", default: "" },
+        railwayUrl: { type: "string", default: "" },
+    },
+});
+/** Ensure daemonId and secret exist; generate if missing. */
+export function ensureIdentity() {
+    let daemonId = store.get("daemonId");
+    let secret = store.get("secret");
+    if (!daemonId) {
+        daemonId = crypto.randomBytes(16).toString("hex");
+        store.set("daemonId", daemonId);
+    }
+    if (!secret) {
+        secret = crypto.randomBytes(32).toString("hex");
+        store.set("secret", secret);
+    }
+    return { daemonId, secret };
+}
+export function getWorkspaceRoot() {
+    return store.get("workspaceRoot") || "";
+}
+export function setWorkspaceRoot(path) {
+    store.set("workspaceRoot", path);
+}
+export function getRailwayUrl() {
+    return store.get("railwayUrl") || "";
+}
+export function setRailwayUrl(url) {
+    store.set("railwayUrl", url);
+}
+export function getConfigPath() {
+    return store.path;
+}
+export function getAllConfig() {
+    return {
+        daemonId: store.get("daemonId") || "",
+        secret: store.get("secret") || "",
+        workspaceRoot: store.get("workspaceRoot") || "",
+        railwayUrl: store.get("railwayUrl") || "",
+    };
+}
+/** Reset identity — used for testing or "unpair" flow. */
+export function resetIdentity() {
+    store.clear();
+}

package/dist/pairing.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Pairing module — generates human-readable pair codes and displays QR.
+ *
+ * Code format: WORD-WORD-NNNN (e.g. AMBER-WOLF-4821)
+ */
+/** Generate a human-readable pair code: WORD-WORD-NNNN */
+export declare function generatePairCode(): string;
+/** Display a QR code in the terminal pointing to the pair URL. */
+export declare function displayPairCode(url: string): void;

package/dist/pairing.js

@@ -0,0 +1,39 @@
+/**
+ * Pairing module — generates human-readable pair codes and displays QR.
+ *
+ * Code format: WORD-WORD-NNNN (e.g. AMBER-WOLF-4821)
+ */
+import crypto from "node:crypto";
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore — no types for qrcode-terminal
+import qrcode from "qrcode-terminal";
+const ADJECTIVES = [
+    "AMBER", "AZURE", "BLAZE", "CEDAR", "CLOUD", "CORAL", "DRIFT",
+    "EMBER", "FROST", "GLEAM", "HAVEN", "IVORY", "LUNAR", "MAPLE",
+    "NOBLE", "OCEAN", "PEARL", "QUIET", "RIVER", "SOLAR", "STORM",
+    "TIDAL", "ULTRA", "VIVID", "SWIFT", "CRISP", "BRAVE", "STARK",
+];
+const NOUNS = [
+    "BEAR", "CROW", "DOVE", "EAGLE", "FALCON", "HAWK", "HERON",
+    "LYNX", "OTTER", "RAVEN", "STAG", "TIGER", "VIPER", "WOLF",
+    "CRANE", "FINCH", "LARK", "PUMA", "ROBIN", "SHARK", "WREN",
+    "BISON", "COBRA", "DRAKE", "GECKO", "IBIS", "KOALA", "MANTA",
+];
+/** Generate a human-readable pair code: WORD-WORD-NNNN */
+export function generatePairCode() {
+    const adj = ADJECTIVES[crypto.randomInt(ADJECTIVES.length)];
+    const noun = NOUNS[crypto.randomInt(NOUNS.length)];
+    const num = crypto.randomInt(1000, 9999);
+    return `${adj}-${noun}-${num}`;
+}
+/** Display a QR code in the terminal pointing to the pair URL. */
+export function displayPairCode(url) {
+    qrcode.generate(url, { small: true }, (code) => {
+        // Indent each line for consistent formatting
+        const indented = code
+            .split("\n")
+            .map((line) => `  ${line}`)
+            .join("\n");
+        console.log(indented);
+    });
+}

package/dist/protocol.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Message protocol for daemon <-> Railway communication.
+ *
+ * All messages are JSON with: { id, type, payload? }
+ * The `id` is for request/response correlation.
+ */
+export interface RegisterMessage {
+    type: "register";
+    daemonId: string;
+    secret: string;
+    version: string;
+    platform: string;
+    workspaceRoot: string;
+}
+export interface PairCodeMessage {
+    type: "pair_code";
+    code: string;
+}
+export interface ToolResultMessage {
+    type: "tool_result";
+    id: string;
+    result?: string;
+    error?: string;
+}
+export interface StreamMessage {
+    type: "stream";
+    id: string;
+    channel: "stdout" | "stderr";
+    data: string;
+}
+export interface StreamDoneMessage {
+    type: "stream_done";
+    id: string;
+    exitCode: number;
+}
+export interface PongMessage {
+    type: "pong";
+}
+export interface NeedsPairingMessage {
+    type: "needs_pairing";
+}
+export interface PairedMessage {
+    type: "paired";
+    appUrl: string;
+}
+export interface ReconnectedMessage {
+    type: "reconnected";
+    appUrl: string;
+}
+export interface ToolExecMessage {
+    type: "tool_exec";
+    id: string;
+    command: string;
+    payload: Record<string, unknown>;
+}
+export interface PingMessage {
+    type: "ping";
+}
+export interface ErrorMessage {
+    type: "error";
+    message: string;
+}
+export type DaemonOutbound = RegisterMessage | PairCodeMessage | ToolResultMessage | StreamMessage | StreamDoneMessage | PongMessage;
+export type RailwayOutbound = NeedsPairingMessage | PairedMessage | ReconnectedMessage | ToolExecMessage | PingMessage | ErrorMessage;
+export declare function encode(msg: DaemonOutbound | RailwayOutbound): string;
+export declare function decode(raw: string): DaemonOutbound | RailwayOutbound;

package/dist/protocol.js

@@ -0,0 +1,13 @@
+/**
+ * Message protocol for daemon <-> Railway communication.
+ *
+ * All messages are JSON with: { id, type, payload? }
+ * The `id` is for request/response correlation.
+ */
+// ─── Helpers ────────────────────────────────────────────────
+export function encode(msg) {
+    return JSON.stringify(msg);
+}
+export function decode(raw) {
+    return JSON.parse(raw);
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "aem-ext-daemon",
+  "version": "0.1.0",
+  "description": "Local daemon for AEM Extension Builder — connects your machine to the cloud UI",
+  "type": "module",
+  "bin": {
+    "aem-ext-daemon": "./bin/cli.js"
+  },
+  "main": "./dist/daemon.js",
+  "types": "./dist/daemon.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node bin/cli.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "conf": "^13.0.1",
+    "qrcode-terminal": "^0.12.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "README.md"
+  ],
+  "keywords": [
+    "adobe",
+    "aem",
+    "extension-builder",
+    "daemon",
+    "local-agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/znikolovski/adobe-extension-builder.git",
+    "directory": "packages/daemon"
+  },
+  "author": "Zoran Nikolovski",
+  "license": "MIT"
+}