@getforgeai/cli 0.1.0-beta.1

package/dist/lib/node-version-guard.js

@@ -0,0 +1,60 @@
+import { createRequire } from "node:module";
+/**
+ * Fail fast, and legibly, on an unsupported Node version.
+ *
+ * Several code paths rely on `import.meta.dirname` (Node 20.11+): the daemon
+ * spawn in lib/daemon.ts, the relay staging in vm/session-manager.ts, and the
+ * agent image build in vm/image-manager.ts. On older Node it is `undefined`,
+ * so `join(undefined, ...)` throws `The "path" argument must be of type
+ * string. Received undefined` — a message that tells the user nothing.
+ *
+ * npm only *warns* on an `engines` mismatch (engine-strict is off by default),
+ * so the install itself does not protect users. This check does.
+ */
+const FALLBACK_MINIMUM = "20.11.0";
+function parse(version) {
+    const [major = 0, minor = 0, patch = 0] = version
+        .replace(/^v/, "")
+        .split(".")
+        .map((part) => Number.parseInt(part, 10) || 0);
+    return [major, minor, patch];
+}
+/** Read the minimum from package.json `engines.node` (e.g. ">=20.11"). */
+function readRequiredVersion() {
+    try {
+        const require = createRequire(import.meta.url);
+        const pkg = require("../../package.json");
+        const range = pkg.engines?.node;
+        const match = range ? /(\d+(?:\.\d+){0,2})/.exec(range) : null;
+        return match ? match[1] : FALLBACK_MINIMUM;
+    }
+    catch {
+        return FALLBACK_MINIMUM;
+    }
+}
+/** True when `current` is at least `required`. Exported for tests. */
+export function isSupportedNodeVersion(current, required) {
+    const [cMajor, cMinor, cPatch] = parse(current);
+    const [rMajor, rMinor, rPatch] = parse(required);
+    if (cMajor !== rMajor)
+        return cMajor > rMajor;
+    if (cMinor !== rMinor)
+        return cMinor > rMinor;
+    return cPatch >= rPatch;
+}
+/**
+ * Print an actionable message and exit(1) when Node is too old.
+ * Called once from the CLI entry point, before anything else runs.
+ */
+export function assertSupportedNodeVersion(current = process.versions.node, required = readRequiredVersion()) {
+    if (isSupportedNodeVersion(current, required))
+        return;
+    process.stderr.write(`\nForgeAI CLI requires Node.js ${required} or newer — you are running v${current}.\n\n` +
+        `Several commands (forge connect, forge vm init) rely on Node APIs added in ${required}\n` +
+        `and fail in confusing ways on older versions.\n\n` +
+        `Upgrade Node, for example:\n` +
+        `  nvm install --lts && nvm use --lts\n` +
+        `  (or download from https://nodejs.org)\n\n`);
+    process.exit(1);
+}
+//# sourceMappingURL=node-version-guard.js.map

package/dist/lib/open-directory.d.ts

@@ -0,0 +1,7 @@
+export type Opener = "terminal" | "vscode" | "finder";
+/**
+ * Open a directory in the configured application.
+ * Cross-platform: macOS, Linux, Windows.
+ */
+export declare function openDirectory(dirPath: string, opener?: Opener): void;
+//# sourceMappingURL=open-directory.d.ts.map

package/dist/lib/open-directory.js

@@ -0,0 +1,41 @@
+import { platform } from "node:os";
+import { spawn } from "node:child_process";
+import chalk from "chalk";
+/**
+ * Open a directory in the configured application.
+ * Cross-platform: macOS, Linux, Windows.
+ */
+export function openDirectory(dirPath, opener = "terminal") {
+    const os = platform();
+    const { cmd, args } = resolveCommand(os, opener, dirPath);
+    console.log(chalk.dim(`[open] Launching: ${cmd} ${args.join(" ")}`));
+    const child = spawn(cmd, args, {
+        detached: true,
+        stdio: "ignore",
+    });
+    child.unref();
+}
+function resolveCommand(os, opener, dirPath) {
+    switch (opener) {
+        case "vscode":
+            return { cmd: "code", args: [dirPath] };
+        case "finder":
+            if (os === "darwin")
+                return { cmd: "open", args: [dirPath] };
+            if (os === "win32")
+                return { cmd: "explorer", args: [dirPath] };
+            return { cmd: "xdg-open", args: [dirPath] };
+        case "terminal":
+        default:
+            if (os === "darwin")
+                return { cmd: "open", args: ["-a", "Terminal", dirPath] };
+            if (os === "win32")
+                return {
+                    cmd: "cmd",
+                    args: ["/c", "start", "cmd", "/K", `cd /d ${dirPath}`],
+                };
+            // Linux: try common terminal emulators
+            return { cmd: "xterm", args: ["-e", `cd '${dirPath}' && $SHELL`] };
+    }
+}
+//# sourceMappingURL=open-directory.js.map

package/dist/lib/repo-manager.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Build the repo path for a project.
+ * Convention: ~/.forgeai/repos/<projectSlug>/
+ */
+export declare function getRepoPath(projectSlug: string): string;
+/**
+ * Check if a directory exists and is a git repo (has .git/ directory).
+ * Distinguishes real repos from worktrees (which have a .git *file*, not a directory).
+ */
+export declare function repoExists(targetDir: string): boolean;
+/**
+ * Clone a git repository to the target directory.
+ * Validates URL format before cloning to prevent command injection.
+ */
+export declare function cloneRepo(repoUrl: string, targetDir: string): Promise<void>;
+/**
+ * Fetch all remote refs for a repository.
+ * Non-fatal on failure — worktree creation may still succeed with stale refs.
+ */
+export declare function fetchRepo(repoDir: string): Promise<void>;
+/**
+ * Resolve the local repo path for a project.
+ * - If repoUrl is provided: clone if missing, fetch if existing
+ * - If repoUrl is missing: fall back to process.cwd() with deprecation warning
+ *
+ * Uses per-project mutex to serialize clone/fetch operations.
+ */
+export declare function resolveRepoPath(projectSlug: string, repoUrl?: string): Promise<string>;
+//# sourceMappingURL=repo-manager.d.ts.map

package/dist/lib/repo-manager.js

@@ -0,0 +1,103 @@
+import { existsSync, statSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Mutex } from "async-mutex";
+import chalk from "chalk";
+const execFileAsync = promisify(execFile);
+// Per-project mutex to serialize clone/fetch operations
+const repoMutexes = new Map();
+function getRepoMutex(projectSlug) {
+    let mutex = repoMutexes.get(projectSlug);
+    if (!mutex) {
+        mutex = new Mutex();
+        repoMutexes.set(projectSlug, mutex);
+    }
+    return mutex;
+}
+// Require a real host after protocol (not just "https://" or "git@.:")
+const VALID_GIT_URL = /^(https?:\/\/[\w.-]+\w(\/|$)|git@\w[\w.-]*:)/;
+/**
+ * Build the repo path for a project.
+ * Convention: ~/.forgeai/repos/<projectSlug>/
+ */
+export function getRepoPath(projectSlug) {
+    return join(homedir(), ".forgeai", "repos", projectSlug);
+}
+/**
+ * Check if a directory exists and is a git repo (has .git/ directory).
+ * Distinguishes real repos from worktrees (which have a .git *file*, not a directory).
+ */
+export function repoExists(targetDir) {
+    const gitPath = join(targetDir, ".git");
+    if (!existsSync(gitPath))
+        return false;
+    try {
+        return statSync(gitPath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Clone a git repository to the target directory.
+ * Validates URL format before cloning to prevent command injection.
+ */
+export async function cloneRepo(repoUrl, targetDir) {
+    if (!VALID_GIT_URL.test(repoUrl)) {
+        throw new Error(`Invalid git URL format: ${repoUrl}`);
+    }
+    console.log(chalk.cyan(`[repo-manager] Cloning ${repoUrl} to ${targetDir}`));
+    const { stderr } = await execFileAsync("git", ["clone", repoUrl, targetDir], {
+        timeout: 120_000, // 2 min timeout for large repos
+    });
+    if (stderr) {
+        // git clone outputs progress to stderr even on success
+        console.log(chalk.dim(`[repo-manager] ${stderr.trim()}`));
+    }
+    console.log(chalk.green(`[repo-manager] Clone complete: ${targetDir}`));
+}
+/**
+ * Fetch all remote refs for a repository.
+ * Non-fatal on failure — worktree creation may still succeed with stale refs.
+ */
+export async function fetchRepo(repoDir) {
+    try {
+        await execFileAsync("git", ["fetch", "--all"], {
+            cwd: repoDir,
+            timeout: 60_000, // 1 min timeout
+        });
+        console.log(chalk.green(`[repo-manager] Fetched all refs for ${repoDir}`));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(chalk.yellow(`[repo-manager] git fetch failed for ${repoDir}: ${message}`));
+        // Non-fatal — worktree creation may still succeed with stale refs
+    }
+}
+/**
+ * Resolve the local repo path for a project.
+ * - If repoUrl is provided: clone if missing, fetch if existing
+ * - If repoUrl is missing: fall back to process.cwd() with deprecation warning
+ *
+ * Uses per-project mutex to serialize clone/fetch operations.
+ */
+export async function resolveRepoPath(projectSlug, repoUrl) {
+    if (!repoUrl) {
+        console.warn(chalk.yellow("[repo-manager] No repoUrl provided, falling back to process.cwd() (deprecated)"));
+        return process.cwd();
+    }
+    const targetDir = getRepoPath(projectSlug);
+    const mutex = getRepoMutex(projectSlug);
+    return mutex.runExclusive(async () => {
+        if (repoExists(targetDir)) {
+            await fetchRepo(targetDir);
+        }
+        else {
+            await cloneRepo(repoUrl, targetDir);
+        }
+        return targetDir;
+    });
+}
+//# sourceMappingURL=repo-manager.js.map

package/dist/lib/resilient-emitter.d.ts

@@ -0,0 +1,53 @@
+import type { AgentStatusPayload, TaskUpdatePayload, CliHeartbeatPayload, SyncRequest, SyncResponse } from "@getforgeai/protocol";
+import type { EventJournal } from "./event-journal.js";
+type SocketClient = {
+    socket: {
+        connected: boolean;
+        on(event: string, handler: (...args: never[]) => void): unknown;
+    };
+    emitAgentStatus: (payload: Omit<AgentStatusPayload, "orgId" | "timestamp">) => unknown;
+    emitTaskUpdate: (payload: Omit<TaskUpdatePayload, "orgId" | "timestamp">) => unknown;
+    emitCliHeartbeat: (payload: Omit<CliHeartbeatPayload, "orgId" | "timestamp">) => unknown;
+};
+type RestClient = {
+    syncEvents: (data: SyncRequest) => Promise<SyncResponse>;
+};
+type ResilientEmitterOptions = {
+    socketClient: SocketClient;
+    restClient: RestClient;
+    journal: EventJournal;
+    cliId: string;
+    orgId: string;
+    projectId?: string;
+    initialCursor?: string;
+    onSyncStart?: () => void;
+    onSyncComplete?: (count: number) => void;
+    onSyncError?: (error: Error) => void;
+};
+export declare class ResilientEmitter {
+    private readonly socketClient;
+    private readonly restClient;
+    private readonly journal;
+    private readonly cliId;
+    private readonly orgId;
+    private readonly projectId;
+    private connected;
+    private syncing;
+    private lastSyncCursor;
+    readonly onSyncStart?: () => void;
+    readonly onSyncComplete?: (count: number) => void;
+    readonly onSyncError?: (error: Error) => void;
+    constructor(options: ResilientEmitterOptions);
+    private setupConnectionListeners;
+    isConnected(): boolean;
+    emitAgentStatus(payload: Omit<AgentStatusPayload, "orgId" | "timestamp">): void;
+    emitTaskUpdate(payload: Omit<TaskUpdatePayload, "orgId" | "timestamp">): void;
+    emitCliHeartbeat(payload: Omit<CliHeartbeatPayload, "orgId" | "timestamp">): void;
+    private appendToJournal;
+    syncPendingEvents(): Promise<number>;
+    private syncWithRetry;
+    getPendingCount(): number;
+    getLastSyncCursor(): string;
+}
+export {};
+//# sourceMappingURL=resilient-emitter.d.ts.map

package/dist/lib/resilient-emitter.js

@@ -0,0 +1,160 @@
+const BATCH_SIZE = 100;
+const MAX_RETRIES = 5;
+const BACKOFF_BASE_MS = 1_000;
+const BACKOFF_MAX_MS = 30_000;
+export class ResilientEmitter {
+    socketClient;
+    restClient;
+    journal;
+    cliId;
+    orgId;
+    projectId;
+    connected;
+    syncing = false;
+    lastSyncCursor;
+    onSyncStart;
+    onSyncComplete;
+    onSyncError;
+    constructor(options) {
+        this.socketClient = options.socketClient;
+        this.restClient = options.restClient;
+        this.journal = options.journal;
+        this.cliId = options.cliId;
+        this.orgId = options.orgId;
+        this.projectId = options.projectId ?? null;
+        this.connected = options.socketClient.socket.connected;
+        this.lastSyncCursor = options.initialCursor ?? "";
+        this.onSyncStart = options.onSyncStart;
+        this.onSyncComplete = options.onSyncComplete;
+        this.onSyncError = options.onSyncError;
+        this.setupConnectionListeners();
+    }
+    setupConnectionListeners() {
+        this.socketClient.socket.on("connect", () => {
+            this.connected = true;
+            void this.syncPendingEvents();
+        });
+        this.socketClient.socket.on("disconnect", () => {
+            this.connected = false;
+        });
+    }
+    isConnected() {
+        return this.connected;
+    }
+    emitAgentStatus(payload) {
+        const timestamp = new Date().toISOString();
+        // Journal meaningful events (not heartbeats)
+        this.appendToJournal({
+            type: "agent:status",
+            timestamp,
+            payload: payload,
+        });
+        if (this.connected) {
+            this.socketClient.emitAgentStatus(payload);
+        }
+    }
+    emitTaskUpdate(payload) {
+        const timestamp = new Date().toISOString();
+        this.appendToJournal({
+            type: "task:update",
+            timestamp,
+            payload: payload,
+        });
+        if (this.connected) {
+            this.socketClient.emitTaskUpdate(payload);
+        }
+    }
+    emitCliHeartbeat(payload) {
+        // Heartbeats are NOT journaled (ephemeral, high-frequency)
+        // Only emit via socket when connected
+        if (this.connected) {
+            this.socketClient.emitCliHeartbeat(payload);
+        }
+    }
+    appendToJournal(event) {
+        this.journal.append({
+            ...event,
+            cliId: this.cliId,
+            orgId: this.orgId,
+            projectId: this.projectId,
+        });
+    }
+    async syncPendingEvents() {
+        if (this.syncing)
+            return 0;
+        this.syncing = true;
+        this.onSyncStart?.();
+        let totalSynced = 0;
+        try {
+            while (true) {
+                const pending = this.journal.readSince(this.lastSyncCursor);
+                if (pending.length === 0)
+                    break;
+                // Batch into chunks
+                const batch = pending.slice(0, BATCH_SIZE);
+                const syncRequest = {
+                    cliId: this.cliId,
+                    projectId: this.projectId ?? undefined,
+                    events: batch.map((e) => ({
+                        eventId: e.eventId,
+                        type: e.type,
+                        timestamp: e.timestamp,
+                        cliId: e.cliId,
+                        orgId: e.orgId,
+                        projectId: e.projectId,
+                        payload: e.payload,
+                    })),
+                    cursor: this.lastSyncCursor || undefined,
+                };
+                const response = await this.syncWithRetry(syncRequest);
+                totalSynced += response.accepted;
+                // Only advance cursor and clear journal when events were actually accepted
+                // (prevents data loss on rate-limited or rejected responses)
+                if (response.accepted > 0) {
+                    const lastEvent = batch.at(-1);
+                    this.lastSyncCursor = lastEvent.eventId;
+                    this.journal.clear(lastEvent.eventId);
+                }
+                // If we processed less than a full batch or none were accepted, we're done
+                if (batch.length < BATCH_SIZE || response.accepted === 0)
+                    break;
+            }
+            if (totalSynced > 0) {
+                this.onSyncComplete?.(totalSynced);
+            }
+        }
+        catch (error) {
+            this.onSyncError?.(error instanceof Error ? error : new Error(String(error)));
+        }
+        finally {
+            this.syncing = false;
+        }
+        return totalSynced;
+    }
+    async syncWithRetry(request) {
+        let lastError;
+        for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+            if (attempt > 0) {
+                const delay = Math.min(BACKOFF_BASE_MS * Math.pow(2, attempt - 1), BACKOFF_MAX_MS);
+                await sleep(delay);
+            }
+            try {
+                return await this.restClient.syncEvents(request);
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+            }
+        }
+        throw lastError ?? new Error("Sync failed after retries");
+    }
+    getPendingCount() {
+        return this.journal.pendingCount();
+    }
+    getLastSyncCursor() {
+        return this.lastSyncCursor;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=resilient-emitter.js.map

package/dist/lib/rest-client.d.ts

@@ -0,0 +1,164 @@
+import type { HeartbeatRequest, HeartbeatResponse, SyncRequest, SyncResponse, TaskPostBody, TaskResponse } from "@getforgeai/protocol";
+type RestClientOptions = {
+    timeoutMs?: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
+};
+type RegisterCliRequest = {
+    cliId: string;
+    name?: string;
+    agentType?: string;
+    agentSlots?: number;
+};
+type RegisterCliResponse = {
+    id: string;
+    cliId: string;
+    name: string;
+    memberId: string;
+    agentType: string;
+    agentSlots: number;
+    createdAt: string;
+};
+type CliDeviceItem = {
+    id: string;
+    cliId: string;
+    name: string;
+    memberId: string;
+    memberName: string;
+    memberEmail: string;
+    agentType: string;
+    agentSlots: number;
+    lastSeenAt: string | null;
+    createdAt: string;
+};
+type ListCliDevicesResponse = {
+    devices: CliDeviceItem[];
+};
+type ProjectState = {
+    tasks: unknown[];
+    tasksAvailable: boolean;
+    agents: unknown[];
+    agentsAvailable: boolean;
+    clis: {
+        cliId: string;
+        name: string;
+        status: string;
+        agentSlots: number;
+        lastSeenAt: string | null;
+    }[];
+    lastSyncTimestamp: string;
+    projectId: string | null;
+};
+type UpdateCliConfigRequest = {
+    cliId: string;
+    name?: string;
+    agentType?: string;
+    agentSlots?: number;
+};
+type TaskDetail = {
+    id: string;
+    title: string;
+    description: string;
+    completed: boolean;
+    kanbanSubStatus: string | null;
+    kanbanColumn: string | null;
+    assigneeId?: string | null;
+    cliDeviceId?: string | null;
+    taskBranch?: string | null;
+    project?: {
+        slug: string;
+        repoUrl: string | null;
+    };
+};
+type WorkflowDetail = {
+    id: string;
+    name: string;
+    slug: string;
+    status: string;
+    baseBranch: string | null;
+    sourceBranch: string | null;
+    project: {
+        slug: string;
+        repoUrl: string | null;
+    };
+};
+type ReleaseDetail = {
+    id: string;
+    version: string;
+    releaseBranch: string | null;
+    targetBranch: string;
+    project: {
+        slug: string;
+        repoUrl: string | null;
+    };
+};
+type TaskRequeueResult = {
+    allowed: boolean;
+    count: number;
+    max: number;
+    reason?: string;
+};
+type TaskAdvanceResult = {
+    advanced: boolean;
+    previousColumn?: string;
+    newColumn?: string;
+    newSubStatus?: string;
+    terminal?: boolean;
+    released?: boolean;
+    column?: string;
+};
+type RestClient = {
+    heartbeat: (data: HeartbeatRequest) => Promise<HeartbeatResponse>;
+    getTasks: () => Promise<TaskResponse>;
+    getTask: (taskId: string) => Promise<TaskDetail>;
+    /** @deprecated Use updateTaskSubStatus instead */
+    updateTaskStatus: (data: TaskPostBody) => Promise<{
+        status: string;
+        taskId: string;
+    }>;
+    updateTaskSubStatus: (data: {
+        taskId: string;
+        kanbanSubStatus: string;
+        agentQuestion?: string;
+    }) => Promise<{
+        status: string;
+        taskId: string;
+    }>;
+    requeueTask: (taskId: string, reason?: string, errorReason?: string, resetAt?: string) => Promise<TaskRequeueResult>;
+    advanceTask: (taskId: string, options?: {
+        fallback?: boolean;
+    }) => Promise<TaskAdvanceResult>;
+    respondToAgent: (taskId: string, response: string) => Promise<{
+        success: boolean;
+    }>;
+    syncEvents: (data: SyncRequest) => Promise<SyncResponse>;
+    registerCli: (data: RegisterCliRequest) => Promise<RegisterCliResponse>;
+    updateCliConfig: (data: UpdateCliConfigRequest) => Promise<RegisterCliResponse>;
+    listCliDevices: () => Promise<ListCliDevicesResponse>;
+    unlinkCli: (data: {
+        cliId: string;
+    }) => Promise<{
+        status: string;
+    }>;
+    disconnectCli: (data: {
+        cliId: string;
+    }) => Promise<{
+        status: string;
+    }>;
+    getProjectState: (projectId?: string) => Promise<ProjectState>;
+    getSkill: (skillName: string) => Promise<unknown>;
+    getWorkflow: (workflowId: string) => Promise<WorkflowDetail>;
+    getRelease: (releaseId: string) => Promise<ReleaseDetail>;
+};
+export declare function createRestClient(serverUrl: string, token: string, orgId: string, options?: RestClientOptions): RestClient;
+type OrgSelectionResponse = {
+    orgIds: string[];
+    orgSlugs: string[];
+};
+export declare function getOrgSelection(serverUrl: string, token: string, userCode: string): Promise<OrgSelectionResponse>;
+export declare class RestClientError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+export {};
+//# sourceMappingURL=rest-client.d.ts.map