@lore-co/cli 0.1.27 → 0.1.29

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { COMMAND_GUIDES, ROOT_HELP, helpTopic } from "./command-help.js";
 import { runShareCommand } from "./share.js";
 import { codexApprovalDetail, inspectCodexHookApproval } from "./codex-hook-approval.js";
 import { claudeOnlyCommand, disableDevinCli, runDevinCliHook } from "./devin-cli.js";
@@ -17,7 +18,7 @@ import { runAskCommand } from "./ask.js";
 import { runRememberCommand } from "./remember.js";
 import { runGuardCommand } from "./guard.js";
 import { runContinueCommand, runResumeCommand } from "./handoff.js";
-import { disableRecovery, prepareRecoveryInstallation, runRecoveryCommand, runRecoveryHook, runWrappedAgent } from "./recovery.js";
+import { disableRecovery, prepareAutomaticRecovery, prepareRecoveryInstallation, runRecoveryCommand, runRecoveryHook, runWrappedAgent } from "./recovery.js";
 import { LAUNCHABLE_AGENTS, isLaunchable, isRecoverySource } from "./agents.js";
 import { runAttachCommand, runLiveHostCommand, runLiveRunCommand, } from "./live.js";
 import { runMachinesCommand } from "./machine.js";
@@ -26,6 +27,7 @@ import { runDevinCommand } from "./devin.js";
 import { runHostCommand } from "./host.js";
 import { runDemoCommand } from "./demo.js";
 import { updateCommand } from "./update.js";
+import { UNINSTALL_HELP, uninstallCommand } from "./uninstall.js";
 import { runSelfHostCommand } from "./self-host.js";
 import { ReliabilityStore, ReliabilityStoreError, integrationInvocationStateKey, } from "./reliability-store.js";
 import { IS_STANDALONE_BINARY, LORE_VERSION } from "./version.js";
@@ -78,62 +80,6 @@ const AGENT_MANIFESTS = {
     opencode: OPENCODE_RELIABILITY_INTEGRATION,
     polytoken: POLYTOKEN_RELIABILITY_INTEGRATION,
 };
-const ROOT_HELP = `lore
-Connect local coding agents to Lore shared engineering memory.
-
-Usage:
-  lore <command> [options]
-
-Commands:
-  connect      Configure Lore and install native agent integrations
-  share        Get a private workspace link to a learning, session, or delivery
-  ask          Query shared knowledge and prior session context
-  remember     Save a durable fact, convention, correction, or decision
-  guard        Control Context Guard (off, assist, enforce)
-  resume       Continue previous work with saved Lore context
-  continue     Hand the current work to a different agent (--on <agent>)
-  run          Run a coding agent with configured recovery
-  recovery     Inspect recovery metrics, record feedback, or disable recovery
-  attach       Reconnect to a live Lore-managed session (--from <machine>)
-  machines     List registered machines and their live sessions
-  github       Prepare/post GitHub reviews and observe corrections
-  devin        Start and manage Lore-enabled Devin sessions
-  host         Call auditable APIs from external agent hosts
-  status       Show connector and agent integration state
-  doctor       Diagnose configuration, integrations, and API reachability
-  self-host    Run a version-pinned local Docker Compose deployment
-  demo         Prove a file-scoped Claude-to-Codex handoff
-  update       Install the latest Lore CLI binary
-  disconnect   Remove Lore-owned integrations and local credentials
-  hook         Internal native hook handler
-
-Discover:
-  lore connect --help
-  lore ask --help
-  lore remember --help
-  lore guard --help
-  lore resume --help
-  lore continue --help
-  lore attach --help
-  lore status --help
-  lore doctor --help
-  lore self-host --help
-  lore disconnect --help
-  lore host --help
-
-Examples:
-  lore connect --token "$LORE_WORKSPACE_TOKEN"
-  lore ask "How should payment retries work?"
-  lore remember "Use pnpm for this repository." --repo acme/app
-  lore resume
-  lore continue --on codex
-  lore connect github --repo owner/repository
-  lore status --json
-  lore doctor
-  lore demo
-  lore update
-  lore devin --help
-`;
 const CONNECT_HELP = `lore connect
 Authorize this device and idempotently install agent integrations.
 
@@ -150,6 +96,7 @@ Options:
   --agent <name>        claude, codex, copilot, copilot-cli, copilot-vscode, cowork, cursor, opencode, polytoken, or t3code
   --timeout-ms <ms>     Hook request timeout, 250-10000 (default: 2500)
   --fallback <agent>   claude, codex, opencode, devin, cursor, copilot-cli, polytoken
+  --no-recovery        Disable automatic handoff setup (otherwise enabled with two installed clients)
   --json                Print machine-readable output
   --help                Show this command's help
 
@@ -990,7 +937,7 @@ function parseConnectorConfig(value) {
         timeoutMs,
     };
 }
-async function readConnectorConfig(paths) {
+export async function readConnectorConfig(paths) {
     try {
         return parseConnectorConfig(JSON.parse(await readFile(paths.config, "utf8")));
     }
@@ -1567,6 +1514,10 @@ function parseConnectArguments(args) {
             parsed.openBrowser = false;
             continue;
         }
+        if (argument === "--no-recovery") {
+            parsed.recovery = false;
+            continue;
+        }
         if (argument !== "--url" &&
             argument !== "--dashboard-url" &&
             argument !== "--token" &&
@@ -1638,8 +1589,8 @@ export async function connectWithCredential(options) {
         throw new Error("Lore agent integrations currently support macOS and Linux");
     }
     const paths = getLorePaths(options.home, options.home === undefined ? process.env : {}, options.cwd);
-    const installRecovery = options.fallback === undefined ? undefined :
-        await prepareRecoveryInstallation(paths, options.fallback, options.home === undefined ? process.env : { ...process.env, ZDOTDIR: paths.home });
+    if (options.recovery === false && options.fallback)
+        throw new Error("--no-recovery cannot be combined with --fallback.");
     const existing = await readConnectorConfig(paths);
     const apiUrl = normalizeApiUrl(options.apiUrl);
     const dashboardUrl = options.dashboardUrl === undefined
@@ -1651,6 +1602,17 @@ export async function connectWithCredential(options) {
     }
     const timeoutMs = options.timeoutMs ?? existing?.timeoutMs ?? 2_500;
     const identity = await authenticatedIdentity(apiUrl, token.trim(), timeoutMs);
+    const recoveryEnv = options.home === undefined ? process.env : { ...process.env, ZDOTDIR: paths.home };
+    let recoveryWarning;
+    const externalRecoveryHost = options.agents.some(agent => ["t3code", "cowork", "copilot-vscode"].includes(agent));
+    const installRecovery = options.fallback === undefined ? options.recovery === true ?
+        await prepareAutomaticRecovery(paths, recoveryEnv).catch((error) => { recoveryWarning = `Automatic recovery setup: ${error.message}`; return undefined; }) : undefined :
+        await prepareRecoveryInstallation(paths, options.fallback, recoveryEnv).catch((error) => {
+            // A desktop host can be the source even when only its destination is on PATH.
+            if (externalRecoveryHost && error.message.startsWith("No supported source client is installed."))
+                return undefined;
+            throw error;
+        });
     const recoveryAgents = installRecovery ? [...installRecovery.sources, installRecovery.fallback]
         .filter((agent) => agent !== "devin") : [];
     const requestedAgents = [...new Set([...options.agents, ...recoveryAgents])];
@@ -1743,7 +1705,12 @@ export async function connectWithCredential(options) {
         await credentialStore.transferPendingTo(reliabilityStore);
     }
     await reliabilityStore.releaseAuthBlocked(now);
-    const recoveryNotice = installRecovery ? await installRecovery() : undefined;
+    const recoveryNotice = installRecovery ? await installRecovery() : recoveryWarning;
+    const hostRecoveryWarnings = options.recovery === true || options.fallback
+        ? await (await import("./recovery-hosts.js")).installExternalRecovery(paths, options.agents, options.cwd ?? process.cwd(), options.fallback)
+            .catch((error) => [`Host recovery setup: ${error.message}`]) : [];
+    if (options.recovery === false)
+        await disableRecovery(paths.home);
     return {
         connected: true,
         apiUrl: config.apiUrl,
@@ -1752,7 +1719,7 @@ export async function connectWithCredential(options) {
         config: paths.config,
         changedHookFiles,
         backups,
-        warnings: [...requestedExpansion.warnings, ...(agents.includes("codex")
+        warnings: [...requestedExpansion.warnings, ...hostRecoveryWarnings, ...(agents.includes("codex")
                 ? ["Codex requires hook approval. Open /hooks in Codex and review any new or changed Lore hooks, then start a fresh session. Run lore doctor to verify approval and the first invocation."]
                 : [])],
         ...(recoveryNotice ? { recoveryNotice } : {}),
@@ -1807,6 +1774,8 @@ async function requestDeviceAuthorization(input) {
     const intervalMs = authorization.data.intervalSeconds * 1_000;
     while (Date.now() < expiresAt) {
         await delay(intervalMs);
+        if (Date.now() >= expiresAt)
+            break;
         let pollResponse;
         try {
             pollResponse = await fetch(`${input.apiUrl}/v1/device-authorizations/poll`, {
@@ -1831,10 +1800,23 @@ async function requestDeviceAuthorization(input) {
             }
             continue;
         }
+        if (pollResponse.status >= 500) {
+            await pollResponse.body?.cancel().catch(() => { });
+            continue;
+        }
         if (!pollResponse.ok) {
             throw new Error("Lore browser approval failed. Run connect --login again.");
         }
-        const result = PollDeviceAuthorizationResponseSchema.safeParse(await pollResponse.json().catch(() => null));
+        let body;
+        try {
+            body = await pollResponse.json();
+        }
+        catch (error) {
+            if (!(error instanceof SyntaxError))
+                continue;
+            throw new Error("Lore returned an incompatible device authorization response.");
+        }
+        const result = PollDeviceAuthorizationResponseSchema.safeParse(body);
         if (!result.success) {
             throw new Error("Lore returned an incompatible device authorization response.");
         }
@@ -1842,15 +1824,38 @@ async function requestDeviceAuthorization(input) {
             continue;
         }
         if (result.data.status === "approved") {
-            return result.data.token;
+            return { token: result.data.token, deviceCode: authorization.data.deviceCode };
         }
         if (result.data.status === "denied") {
             throw new Error("Lore access was denied in the dashboard.");
         }
+        if (result.data.status === "consumed") {
+            throw new Error("Lore approval was already completed, but this login did not receive its credential. Run connect --login again.");
+        }
         throw new Error("Lore browser approval expired. Run connect --login again.");
     }
     throw new Error("Lore browser approval expired. Run connect --login again.");
 }
+async function acknowledgeDeviceAuthorization(apiUrl, authorization) {
+    // The credential is already saved. A lost acknowledgement must not undo
+    // login; old servers may lack this endpoint, and unacknowledged grants expire.
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        try {
+            const response = await fetch(`${apiUrl}/v1/device-authorizations/acknowledge`, {
+                method: "POST",
+                headers: { accept: "application/json", "content-type": "application/json" },
+                body: JSON.stringify(authorization),
+                signal: AbortSignal.timeout(2_000),
+            });
+            await response.body?.cancel();
+            if (response.ok || (response.status >= 400 && response.status < 500))
+                return;
+        }
+        catch {
+            // Retry a lost response with the same secrets.
+        }
+    }
+}
 async function connectCommand(args) {
     const parsed = parseConnectArguments(args);
     if (parsed === null) {
@@ -1876,25 +1881,29 @@ async function connectCommand(args) {
     if (parsed.login && hasProvidedToken) {
         throw new Error("--login cannot be combined with an explicit or environment workspace token. Unset it or use the token directly.");
     }
-    const token = parsed.login
+    const authorization = parsed.login
         ? await requestDeviceAuthorization({
             apiUrl,
             ...(dashboardUrl === undefined ? {} : { dashboardUrl }),
             agents: parsed.agents,
             openBrowser: parsed.openBrowser,
         })
-        : configured;
+        : undefined;
+    const token = authorization?.token ?? configured;
     if (token === undefined || token.trim() === "") {
         throw new Error("Workspace token is required. Use --login, --token <token>, LORE_WORKSPACE_TOKEN, or LORE_TOKEN.");
     }
     const result = await connectWithCredential({
         ...(parsed.fallback === undefined ? {} : { fallback: parsed.fallback }),
+        recovery: parsed.recovery ?? true,
         apiUrl,
         ...(dashboardUrl === undefined ? {} : { dashboardUrl }),
         token,
         agents: parsed.agents,
         ...(parsed.timeoutMs === undefined ? {} : { timeoutMs: parsed.timeoutMs }),
     });
+    if (authorization)
+        await acknowledgeDeviceAuthorization(apiUrl, authorization);
     writeResult(result, parsed.json, `access authorized; integrations installed: ${result.agents.join(", ")}\napi_url: ${result.apiUrl}\nconfig: ${result.config}\nRestart your agent and complete a turn, then run lore doctor to verify recording.\n${result.recoveryNotice ? `${result.recoveryNotice}\n` : ""}${result.warnings.map((warning) => `warning: ${warning}\n`).join("")}`);
 }
 async function queueCount(paths) {
@@ -2217,7 +2226,10 @@ async function disconnectCommand(args) {
     if (parsed === null) {
         return;
     }
-    const paths = getLorePaths();
+    const result = await disconnectInstallation();
+    writeResult(result, parsed.json, `disconnected: yes\nchanged_hook_files: ${result.changedHookFiles.length}\n`);
+}
+export async function disconnectInstallation(paths = getLorePaths(), preservePendingState = false) {
     await disableRecovery(paths.home);
     await disableDevinCli(paths.home);
     const config = await readConnectorConfig(paths);
@@ -2267,11 +2279,12 @@ async function disconnectCommand(args) {
         rm(paths.runtimeInvocationHealthWriter, { force: true }),
         rm(paths.runtimeVersion, { force: true }),
         rm(paths.runtimePackage, { force: true }),
-        rm(paths.state, { recursive: true, force: true }),
-        rm(paths.queue, { recursive: true, force: true }),
+        ...(preservePendingState ? [] : [
+            rm(paths.state, { recursive: true, force: true }),
+            rm(paths.queue, { recursive: true, force: true }),
+        ]),
     ]);
-    const result = { connected: false, changedHookFiles, backups };
-    writeResult(result, parsed.json, `disconnected: yes\nchanged_hook_files: ${changedHookFiles.length}\n`);
+    return { connected: false, changedHookFiles, backups };
 }
 async function apiChecks(config) {
     const readinessUrl = `${config.apiUrl}/health/ready`;
@@ -2536,8 +2549,95 @@ async function doctorCommand(args) {
         process.exitCode = 1;
     }
 }
+async function printCommandHelp(path) {
+    const topic = helpTopic(path);
+    process.stdout.write(`When to use: ${COMMAND_GUIDES[topic.command]}\n\n`);
+    if (topic.text) {
+        process.stdout.write(topic.text);
+        return;
+    }
+    const args = [...(topic.subcommand ? [topic.subcommand] : []), "--help"];
+    // Help never loads workspace credentials, makes requests, or runs an agent.
+    switch (topic.command) {
+        case "connect":
+            process.stdout.write(CONNECT_HELP);
+            return;
+        case "status":
+            process.stdout.write(STATUS_HELP);
+            return;
+        case "doctor":
+            process.stdout.write(DOCTOR_HELP);
+            return;
+        case "disconnect":
+            process.stdout.write(DISCONNECT_HELP);
+            return;
+        case "uninstall":
+            process.stdout.write(UNINSTALL_HELP);
+            return;
+        case "share":
+            await runShareCommand(args, null);
+            return;
+        case "ask":
+            await runAskCommand(args, null);
+            return;
+        case "remember":
+            await runRememberCommand(args, null);
+            return;
+        case "guard":
+            await runGuardCommand(args, null);
+            return;
+        case "resume":
+            await runResumeCommand(args, null, getLorePaths());
+            return;
+        case "continue":
+            await runContinueCommand(args, null, getLorePaths());
+            return;
+        case "attach":
+            await runAttachCommand(args, null, getLorePaths());
+            return;
+        case "machines":
+            await runMachinesCommand(args, null, getLorePaths());
+            return;
+        case "host":
+            await runHostCommand(args);
+            return;
+        case "devin":
+            if (topic.subcommand === "cli") {
+                process.stdout.write((await import("./devin-cli.js")).DEVIN_CLI_HELP);
+                return;
+            }
+            await runDevinCommand(args);
+            return;
+        case "self-host":
+            await runSelfHostCommand(args);
+            return;
+        case "demo":
+            await runDemoCommand(args, null);
+            return;
+        case "update":
+            await updateCommand(args);
+            return;
+        default: throw new Error(`Help is unavailable for ${topic.command}`);
+    }
+}
 export async function runCli(args = process.argv.slice(2)) {
     const command = args[0];
+    if (command === "help") {
+        const path = args.slice(1);
+        if (!path.length || (path.length === 1 && ["--help", "-h"].includes(path[0])))
+            process.stdout.write(ROOT_HELP);
+        else
+            await printCommandHelp(path);
+        return;
+    }
+    const separator = args.indexOf("--");
+    const helpIndex = args.findIndex((value, index) => index > 0 && (separator < 0 || index < separator) && (value === "--help" || value === "-h"));
+    if (helpIndex > 0) {
+        const subcommand = args[1];
+        const grouped = ["connect", "guard", "recovery", "github", "devin", "host", "self-host"].includes(command ?? "");
+        await printCommandHelp([command, ...(grouped && subcommand && !subcommand.startsWith("-") ? [subcommand] : [])]);
+        return;
+    }
     if (command === undefined || command === "--help" || command === "-h") {
         process.stdout.write(ROOT_HELP);
         return;
@@ -2577,6 +2677,11 @@ export async function runCli(args = process.argv.slice(2)) {
             await runWrappedAgent(commandArgs, getLorePaths(process.env.LORE_HOME));
             return;
         case "recovery":
+            if (commandArgs[0] === "cloud") {
+                const paths = getLorePaths(process.env.LORE_HOME);
+                await (await import("./recovery-cloud.js")).runCloudRecoveryCommand(commandArgs.slice(1), paths, await readConnectorConfig(paths));
+                return;
+            }
             await runRecoveryCommand(commandArgs, getLorePaths(process.env.LORE_HOME));
             return;
         case "recovery-hook":
@@ -2638,6 +2743,12 @@ export async function runCli(args = process.argv.slice(2)) {
         case "disconnect":
             await disconnectCommand(commandArgs);
             return;
+        case "uninstall":
+            await uninstallCommand(commandArgs, {
+                disconnect: () => disconnectInstallation(getLorePaths(), true),
+                retainedDirectory: getLorePaths().loreDirectory,
+            });
+            return;
         case "devin-cli-hook":
             try {
                 const result = await runDevinCliHook(getLorePaths(process.env.LORE_HOME).home);