propr-cli 0.8.3 → 0.8.4

package/dist/commands/imageCommands.js

@@ -0,0 +1,60 @@
+/**
+ * Docker image maintenance commands for the local ProPR stack.
+ */
+import { Command } from "commander";
+import { createConfigManager } from "../config/index.js";
+import { getHostConfig } from "../orchestrator/index.js";
+async function pullImages(options) {
+    const configManager = await createConfigManager();
+    const { orch, cfg, rootDir } = await getHostConfig({ configManager, root: options.root });
+    if (!orch.dockerAvailable()) {
+        console.error("Error: cannot reach the Docker daemon. Run 'propr check' for diagnostics.");
+        process.exit(1);
+    }
+    console.log(`Pulling ProPR images (root: ${rootDir})`);
+    const env = options.skipRemoteImageCheck
+        ? { ...process.env, PROPR_SKIP_REMOTE_IMAGE_CHECK: "1" }
+        : process.env;
+    const { failedAgentImages, strictAgentPull } = orch.pullImages(cfg, {
+        env,
+        onLog: (line) => console.log(line),
+    });
+    if (failedAgentImages.length > 0) {
+        console.warn(`\nwarning: ${failedAgentImages.length} agent image(s) could not be pulled:`);
+        for (const tag of failedAgentImages)
+            console.warn(`    - ${tag}`);
+        console.warn("  Jobs using those agents will fail until the images are available.");
+        if (strictAgentPull)
+            process.exit(1);
+    }
+}
+export function createImagesCommand() {
+    const images = new Command("images")
+        .description("Manage local ProPR Docker images");
+    images
+        .command("pull")
+        .description("Pull missing or stale ProPR Docker images without starting the stack")
+        .option("--root <dir>", "Stack root directory (where .env/data/logs/repos live)")
+        .option("--skip-remote-image-check", "Skip registry freshness checks before deciding what to pull")
+        .addHelpText("after", `
+Examples:
+  $ propr images pull
+  $ propr images pull --skip-remote-image-check
+  $ propr images pull --root ~/propr
+
+Notes:
+  --skip-remote-image-check is for offline runs. It still pulls missing images,
+  but local images are treated as acceptable because stale tags cannot be
+  detected without the registry freshness check.
+`)
+        .action(async (options) => {
+        try {
+            await pullImages(options);
+        }
+        catch (error) {
+            console.error(`Error pulling images: ${error.message}`);
+            process.exit(1);
+        }
+    });
+    return images;
+}

package/dist/commands/index.js

@@ -13,8 +13,10 @@ export { createLogCommand } from "./logCommands.js";
 export { createTodoCommand } from "./todoCommands.js";
 export { createRemoteStatusCommand, createQueueCommand } from "./systemCommands.js";
 export { createInitCommand } from "./initCommands.js";
+export { createSetupCommand } from "./setupCommand.js";
 // Control-plane commands (local Docker stack)
 export { createCheckCommand, runChecks, printChecks, STACK_CONFIG_CHECK_NAME } from "./checkCommands.js";
+export { createImagesCommand } from "./imageCommands.js";
 export { createStartCommand } from "./startCommand.js";
 export { createStackStatusCommand, createStopCommand } from "./stackCommands.js";
 export { createUiCommand, createDocsCommand } from "./uiDocsCommands.js";

package/dist/commands/initStack.js

@@ -9,9 +9,42 @@
 import { Command } from "commander";
 import { existsSync, copyFileSync, chmodSync, mkdirSync, readFileSync, appendFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { dirname, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { homedir } from "node:os";
 import { createConfigManager } from "../config/index.js";
+// Mirrors the launcher's HOST_VIBE_PROMPT_CACHE_DIR default in
+// docker/launcher/orchestrator.mjs. Keep it per-user and private because prompt
+// files can contain task/repository context.
+function defaultVibePromptCacheDir() {
+    return `/tmp/propr-vibe-prompts-${process.getuid?.() ?? "user"}`;
+}
+/**
+ * Pre-create the host Vibe prompt-cache directory owned by the invoking user.
+ *
+ * Spawned Vibe agent containers bind-mount this path. If it does not exist when
+ * Docker first mounts it, the daemon auto-creates it as root, leaving a
+ * root-owned directory the user can no longer write to — which then trips
+ * `validateEnv`'s writability check and blocks `propr start` on every
+ * subsequent run. Creating it here (owned by the user, 0700) avoids that.
+ *
+ * Returns the directory if it was created, otherwise `undefined`. Safe to call
+ * repeatedly: an existing directory (regardless of owner) is left untouched.
+ */
+export function ensureVibePromptCacheDir(cacheDir) {
+    if (!cacheDir)
+        return undefined;
+    // Skip container-only / Docker-special paths (a ':' would be a volume spec).
+    if (!isAbsolute(cacheDir) || cacheDir.includes(":"))
+        return undefined;
+    if (existsSync(cacheDir))
+        return undefined;
+    mkdirSync(cacheDir, { recursive: true, mode: 0o700 });
+    try {
+        chmodSync(cacheDir, 0o700);
+    }
+    catch { /* best-effort: keep prompt material private */ }
+    return cacheDir;
+}
 /** Resolve the bundled .env.example, falling back to a repo checkout. */
 function resolveEnvExample() {
     const here = dirname(fileURLToPath(import.meta.url));
@@ -119,6 +152,22 @@ export async function scaffoldStack(options = {}) {
     }
     result.detected = detected;
     result.pendingCredentials = toAppend;
+    // 3b. When Vibe is in play, pre-create its prompt-cache dir so spawned Vibe
+    //     agent containers can bind-mount a writable host directory. Creating it
+    //     here (owned by the invoking user) avoids Docker auto-creating it as
+    //     root. Defaults to a per-user /tmp/propr-vibe-prompts-$uid path
+    //     (matching the launcher default); an explicit
+    //     HOST_VIBE_PROMPT_CACHE_DIR is honored.
+    const vibeConfigured = detected.some((c) => c.envKey === "HOST_VIBE_DIR") ||
+        /^\s*(?:export\s+)?(?:HOST_VIBE_DIR|MISTRAL_API_KEY)\s*=\s*\S/m.test(envContent);
+    if (vibeConfigured) {
+        const match = envContent.match(/^\s*(?:export\s+)?HOST_VIBE_PROMPT_CACHE_DIR\s*=\s*(.+)\s*$/m);
+        const configured = match?.[1]?.trim().replace(/^["']|["']$/g, "");
+        const cacheDir = configured || defaultVibePromptCacheDir();
+        const created = ensureVibePromptCacheDir(cacheDir);
+        if (created)
+            result.dirsCreated.push(created);
+    }
     // 4. Persist the stack root so other commands can find it.
     const configManager = await createConfigManager();
     await configManager.setStackRoot(rootDir);

package/dist/commands/relayCommands.js

@@ -10,41 +10,67 @@
 import { Command } from "commander";
 import { hostname } from "node:os";
 import { join } from "node:path";
-import { validateRelayUrl } from "../vendor/shared/index.js";
+import { validateRelayUrl, DEFAULT_PROPR_GH_RELAY_URL } from "../vendor/shared/index.js";
 import { createConfigManager } from "../config/index.js";
 import { loadOrchestrator, resolveStackRoot } from "../orchestrator/index.js";
 import { upsertEnvVars } from "../utils/envFile.js";
-import { enrollRelayToken, listRelayTokens, revokeRelayToken, } from "../api/relay.js";
+import { enrollRelayToken, fetchAuthenticatedUser, listRelayTokens, revokeRelayToken, } from "../api/relay.js";
 async function resolveContext(options) {
     const configManager = await createConfigManager();
     const rootDir = resolveStackRoot(configManager, options.root);
     const envPath = join(rootDir, ".env");
     const orch = await loadOrchestrator();
     const fileEnv = orch.readEnvFile(envPath);
-    const relayBaseUrl = options.url ?? process.env.PROPR_GH_RELAY_URL ?? fileEnv.PROPR_GH_RELAY_URL;
-    if (!relayBaseUrl) {
-        throw new Error("No relay URL. Pass --url <https://relay/v1> or set PROPR_GH_RELAY_URL in .env (run `propr init stack` first).");
-    }
+    // Falls back to the hosted relay (webhook.propr.dev) so `propr relay enroll`
+    // works out of the box; an explicit --url or PROPR_GH_RELAY_URL overrides it
+    // for self-hosted relays.
+    const relayBaseUrl = options.url ??
+        process.env.PROPR_GH_RELAY_URL ??
+        fileEnv.PROPR_GH_RELAY_URL ??
+        DEFAULT_PROPR_GH_RELAY_URL;
     const urlError = validateRelayUrl(relayBaseUrl);
     if (urlError) {
         throw new Error(urlError);
     }
-    const installationId = options.installation ?? process.env.GH_INSTALLATION_ID ?? fileEnv.GH_INSTALLATION_ID;
-    if (!installationId) {
-        throw new Error("No installation id. Pass --installation <id> or set GH_INSTALLATION_ID in .env.");
-    }
     const githubToken = configManager.getGithubToken();
     if (!githubToken) {
         throw new Error("Not logged in to GitHub. Run `propr login` first.");
     }
+    const client = { baseUrl: relayBaseUrl, githubToken };
+    // Explicit flag / env / .env win; otherwise ask the relay which installations
+    // this GitHub identity can access and auto-select when there's exactly one.
+    const installationId = options.installation ??
+        process.env.GH_INSTALLATION_ID ??
+        fileEnv.GH_INSTALLATION_ID ??
+        (await discoverInstallationId(client));
     return {
         rootDir,
         envPath,
         relayBaseUrl,
         installationId,
-        client: { baseUrl: relayBaseUrl, githubToken },
+        client,
     };
 }
+// Discovery fallback when no installation id was supplied: query the relay for
+// the installations this GitHub identity can access. Auto-select the only one;
+// otherwise fail with an actionable message (zero installs vs. ambiguous choice).
+export async function discoverInstallationId(client) {
+    const { installations } = await fetchAuthenticatedUser(client);
+    if (installations.length === 1) {
+        const only = installations[0];
+        // To stderr, not stdout: `relay list --json` must emit only the JSON body,
+        // so this informational notice must stay out of the data stream.
+        console.error(`Using installation ${only.installation_id} (${only.account_login}) — the only one available to you.`);
+        return String(only.installation_id);
+    }
+    if (installations.length === 0) {
+        throw new Error("No GitHub App installation is available for your account. Install the shared ProPR GitHub App, then retry — or pass --installation <id>.");
+    }
+    const options = installations
+        .map((i) => `  ${i.installation_id}  ${i.account_login} (${i.account_type})`)
+        .join("\n");
+    throw new Error(`Multiple installations are available; pass --installation <id> to choose one:\n${options}`);
+}
 export function createRelayCommand() {
     const relay = new Command("relay")
         .description("Manage GitHub token relay enrollment (shared-app auth path)")
@@ -52,8 +78,15 @@ export function createRelayCommand() {
 The relay lets a shared-app stack obtain GitHub installation tokens without
 holding the App's private key. Enroll once; the token is saved to your .env.
 
+The relay URL defaults to the hosted service (${DEFAULT_PROPR_GH_RELAY_URL});
+pass --url only when running a self-hosted relay.
+
+The installation id is discovered automatically when you have exactly one;
+pass --installation <id> to disambiguate or override it.
+
 Examples:
-  $ propr relay enroll --url https://relay.propr.dev/v1
+  $ propr relay enroll
+  $ propr relay enroll --url https://relay.example.com/v1
   $ propr relay list
   $ propr relay revoke <token-id>
 `);

package/dist/commands/setup/agents.js

@@ -0,0 +1,185 @@
+/**
+ * Agent enablement + image-based authentication for `propr setup`.
+ *
+ * This runs as a setup step *after the stack is up* (the backend must be
+ * reachable to read and write agent configuration). It does three things, each
+ * non-destructively:
+ *
+ *   1. Reads the agents already configured in the running backend.
+ *   2. Adds any *selected* agent whose type is not yet configured, seeding it
+ *      from the shared {@link AGENT_DEFAULTS} metadata (alias + supported
+ *      models). Existing agents are never disabled, deleted, or re-aliased — a
+ *      re-run only fills in what is missing.
+ *   3. For selected agents that support an interactive image login (see
+ *      {@link planAgentLogin}), offers to authenticate through the agent's
+ *      Docker image and runs the login only for the ones the user confirms.
+ *
+ * Like the engine, this module is UI-agnostic: the side effects live behind the
+ * injectable {@link AgentSetupActions} seam (tests pass mocks so the flow runs
+ * without Docker, the network, or a TTY) and the single user decision is
+ * collected through the optional {@link AgentSetupParams.confirmLogin} callback
+ * (a missing callback means "authenticate nothing", the safe default).
+ */
+import { AGENT_DEFAULTS } from "../../vendor/shared/index.js";
+/**
+ * Enable the selected agents in the running backend and, on confirmation,
+ * authenticate the ones that support an image login. Never throws for expected
+ * conditions — every failure is captured in {@link AgentSetupOutcome.errors} so
+ * the caller can settle the step as a warning rather than aborting setup.
+ */
+export async function runAgentSetup(params) {
+    const { rootDir, selectedAgents, actions, confirmLogin, onLog } = params;
+    const outcome = {
+        added: [],
+        alreadyConfigured: [],
+        authenticated: [],
+        authFailed: [],
+        errors: [],
+    };
+    if (selectedAgents.length === 0)
+        return outcome;
+    // 1. Read the current backend configuration. Without it we cannot safely tell
+    //    which agents are new, so a read failure stops here (nothing was changed).
+    let existing;
+    try {
+        existing = await actions.listAgents(rootDir);
+    }
+    catch (error) {
+        outcome.errors.push(`could not read backend agents: ${error.message}`);
+        return outcome;
+    }
+    // 2. Add the selected agents that are not yet configured. Match by type so we
+    //    never add a second agent for a type the user already runs — existing
+    //    agents (enabled or not) are left exactly as they are.
+    const configuredTypes = new Set(existing.map((agent) => agent.type));
+    for (const type of selectedAgents) {
+        if (configuredTypes.has(type)) {
+            outcome.alreadyConfigured.push(type);
+            continue;
+        }
+        const defaults = AGENT_DEFAULTS[type];
+        if (!defaults)
+            continue; // unknown type — guarded, but never trust the input
+        try {
+            onLog?.(`enabling agent ${type}…`);
+            // Seed from shared metadata: alias + the full supported-model set. The
+            // backend resolves the default docker image and host config path, so we
+            // don't pass them (a literal "~" path would otherwise reach the backend).
+            await actions.addAgent(rootDir, {
+                alias: defaults.defaultAlias,
+                type: type,
+                models: defaults.defaultModels,
+                enabled: true,
+            });
+            outcome.added.push(type);
+            configuredTypes.add(type);
+        }
+        catch (error) {
+            outcome.errors.push(`could not enable ${type}: ${error.message}`);
+        }
+    }
+    // 3. Image-based authentication — only for selected agents that actually have
+    //    a login plan, and only for the ones the user confirms.
+    let loginable;
+    try {
+        loginable = new Set(await actions.loginableAgents());
+    }
+    catch (error) {
+        outcome.errors.push(`could not determine which agents support image login: ${error.message}`);
+        return outcome;
+    }
+    const candidates = selectedAgents.filter((type) => loginable.has(type));
+    if (candidates.length === 0 || !confirmLogin)
+        return outcome;
+    let chosen;
+    try {
+        chosen = await confirmLogin({ candidates, rootDir });
+    }
+    catch (error) {
+        // A failed/cancelled prompt must not abort the whole run — just skip login.
+        outcome.errors.push(`agent login prompt failed: ${error.message}`);
+        return outcome;
+    }
+    const chosenSet = new Set(chosen.filter((type) => loginable.has(type)));
+    // Iterate the candidate order (not the user's), so logins run in a stable order.
+    for (const type of candidates) {
+        if (!chosenSet.has(type))
+            continue;
+        try {
+            onLog?.(`authenticating ${type} through its image…`);
+            const result = await actions.loginAgent(rootDir, type);
+            if (result.detail)
+                onLog?.(result.detail);
+            if (result.available && result.success)
+                outcome.authenticated.push(type);
+            else
+                outcome.authFailed.push(type);
+        }
+        catch (error) {
+            outcome.authFailed.push(type);
+            outcome.errors.push(`login for ${type} failed: ${error.message}`);
+        }
+    }
+    return outcome;
+}
+/**
+ * Build the production {@link AgentSetupActions}, lazily importing the heavy
+ * orchestrator/API/validation modules only when an action runs — keeping the
+ * engine import cheap and Docker-free for tests, which replace these anyway.
+ */
+export function createDefaultAgentSetupActions(configManager) {
+    /** A client pointed at the local stack's API port (not the saved remote URL). */
+    const localApiClient = async (rootDir) => {
+        const { getHostConfig } = await import("../../orchestrator/index.js");
+        const { cfg } = await getHostConfig({ configManager, root: rootDir });
+        const { createApiClient } = await import("../../api/client.js");
+        return createApiClient({ baseUrl: `http://localhost:${cfg.apiPort}` });
+    };
+    return {
+        async listAgents(rootDir) {
+            const { listAgents } = await import("../../api/agents.js");
+            const client = await localApiClient(rootDir);
+            const response = await listAgents(client);
+            return response.agents;
+        },
+        async addAgent(rootDir, options) {
+            const { addAgent } = await import("../../api/agents.js");
+            const client = await localApiClient(rootDir);
+            await addAgent(options, client);
+        },
+        async loginableAgents() {
+            const { loginableAgents } = await import("../agentValidation.js");
+            return loginableAgents();
+        },
+        async loginAgent(rootDir, type) {
+            const { mkdirSync, mkdtempSync, rmSync } = await import("node:fs");
+            const { tmpdir } = await import("node:os");
+            const { join } = await import("node:path");
+            const { spawnSync } = await import("node:child_process");
+            const { getHostConfig } = await import("../../orchestrator/index.js");
+            const { planAgentLogin } = await import("../agentValidation.js");
+            const { orch, cfg } = await getHostConfig({ configManager, root: rootDir });
+            const tmp = mkdtempSync(join(tmpdir(), "propr-setup-login-"));
+            const workspaceDir = join(tmp, "workspace");
+            mkdirSync(workspaceDir, { recursive: true });
+            try {
+                const { plan, error } = planAgentLogin(type, cfg, workspaceDir, orch.validateDockerBindPath);
+                if (error || !plan)
+                    return { available: false, success: false, detail: error };
+                // The image must be present locally; setup pulls selected agent images
+                // earlier, but a failed pull would leave it absent.
+                if (orch.docker(["images", "-q", plan.image], { capture: true }).stdout.trim().length === 0) {
+                    return { available: true, success: false, detail: `image ${plan.image} not present locally — run \`propr images pull\`` };
+                }
+                mkdirSync(plan.hostDir, { recursive: true, mode: 0o700 });
+                const res = spawnSync("docker", plan.dockerArgs, { stdio: "inherit" });
+                return res.status === 0
+                    ? { available: true, success: true, detail: `${type} login finished — credentials written to ${plan.hostDir}` }
+                    : { available: true, success: false, detail: `${type} login exited with code ${res.status ?? "?"}` };
+            }
+            finally {
+                rmSync(tmp, { recursive: true, force: true });
+            }
+        },
+    };
+}