@clawscarf/cli 0.1.0-alpha.1

package/scripts/installation/installer/menu.js

@@ -0,0 +1,49 @@
+import { homedir } from "node:os";
+function row(value, label, summary, hint) {
+    return {
+        value,
+        label: `${label.padEnd(24)}${summary}`,
+        ...(hint ? { hint } : {}),
+    };
+}
+export function installationMenu(config, directory, browserAvailable, packIssues, modelSummary, existing = false) {
+    const location = directory.startsWith(homedir() + "/")
+        ? "~" + directory.slice(homedir().length)
+        : directory;
+    const agents = config.packs.flatMap((pack) => pack.members);
+    const choices = [
+        {
+            value: "review",
+            label: existing ? "Review and apply\n" : "Accept settings and continue\n",
+            hint: existing
+                ? "Review before changing the server"
+                : "Credentials come next",
+        },
+        row("location", "Location", location.length > 40 ? "…" + location.slice(-39) : location, directory),
+        row("identity", "Name and administrator", `${config.name} · ${config.access.administratorName}`),
+        row("access", "Access", config.access.mode === "hosted" ? "ClawScarf login" : "Custom OIDC", "Configure your own OIDC provider (optional)"),
+        row("exposure", "Network", config.exposure.mode === "local"
+            ? "This computer"
+            : config.exposure.applicationOrigin),
+        row("models", "Models", modelSummary ?? "Choose a model"),
+        row("connections", "Connections", config.connections.mode === "disabled" ? "Off" : "On"),
+        row("packs", "Packs", packIssues.length
+            ? "Needs attention"
+            : agents.length
+                ? `${String(agents.length)} agents selected`
+                : "None", packIssues.length ? packIssues.join(" ") : agents.join(", ")),
+        row("resources", "Resources", `${config.resources.runtime.cpu} CPU / ${config.resources.runtime.memory}`, "Protected team runtime"),
+        ...(browserAvailable
+            ? [
+                row("browser", "Browser", config.browser.enabled ? "On (experimental)" : "Off"),
+            ]
+            : []),
+        { value: "advanced-models", label: "Advanced model gateway settings" },
+    ];
+    return existing
+        ? [
+            ...choices.filter(({ value }) => ["review", "models", "connections", "packs"].includes(value)),
+            { value: "model-credentials", label: "Change LLM API keys" },
+        ]
+        : choices;
+}

package/scripts/installation/installer/prompts.js

@@ -0,0 +1,139 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import * as clack from "@clack/prompts";
+import { InstallationError } from "../errors.js";
+export class InstallerCancelled extends Error {
+}
+export class SectionCancelled extends Error {
+}
+/** OSC 8 adds terminal links; the visible URL also works in terminals without it. */
+export function terminalLink(url) {
+    return process.stdout.isTTY && process.env.TERM !== "dumb"
+        ? `\u001b]8;;${url}\u001b\\${url}\u001b]8;;\u001b\\`
+        : url;
+}
+async function answer(work) {
+    const navigation = { back: false };
+    const keypress = (_text, key) => {
+        if (key.name === "escape")
+            navigation.back = true;
+    };
+    process.stdin.on("keypress", keypress);
+    try {
+        const value = await work();
+        if (typeof value === "symbol") {
+            if (navigation.back)
+                throw new SectionCancelled();
+            throw new InstallerCancelled();
+        }
+        return value;
+    }
+    finally {
+        process.stdin.off("keypress", keypress);
+    }
+}
+export const terminalPrompts = {
+    async text(message, initial, validate) {
+        return answer(() => clack.text({
+            message,
+            ...(initial === undefined ? {} : { initialValue: initial }),
+            validate: (value) => validate
+                ? validate(value ?? "")
+                : value?.trim()
+                    ? undefined
+                    : "Enter a value.",
+        }));
+    },
+    async password(message) {
+        return answer(() => clack.password({
+            message,
+            validate: (value) => (value?.trim() ? undefined : "Enter a value."),
+        }));
+    },
+    async select(message, options, initial) {
+        return answer(() => clack.select({
+            message,
+            options,
+            ...(initial === undefined ? {} : { initialValue: initial }),
+        }));
+    },
+    async multiselect(message, options) {
+        return answer(() => clack.multiselect({ message, options, required: true }));
+    },
+    async confirm(message, initialValue = false) {
+        return answer(() => clack.confirm({ message, initialValue }));
+    },
+    note: clack.note,
+    async openBrowser(url) {
+        try {
+            await promisify(execFile)(process.platform === "darwin" ? "open" : "xdg-open", [url], { timeout: 5000 });
+        }
+        catch {
+            process.stderr.write("Could not open a browser. Open the link above manually.\n");
+        }
+    },
+};
+export function requireTerminal() {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        throw new InstallationError("invalid_configuration", "Use configure --non-interactive with explicit options when no terminal is available.");
+}
+export async function progress(message, work, options = {}) {
+    const cancellation = new AbortController();
+    const cancel = () => {
+        if (cancellation.signal.aborted)
+            return;
+        cancellation.abort(new InstallerCancelled());
+        process.stderr.write("Cancellation requested. Waiting for the current operation to settle; no following step will start.\n");
+    };
+    const spinner = !options.json && process.stderr.isTTY
+        ? clack.spinner({ output: process.stderr, onCancel: cancel })
+        : undefined;
+    const report = (detail) => {
+        if (spinner && detail.includes("\n")) {
+            spinner.stop(message);
+            process.stderr.write(detail + "\n");
+            spinner.start(message);
+        }
+        else if (spinner)
+            spinner.message(detail);
+        else
+            process.stderr.write(detail + "\n");
+    };
+    if (spinner)
+        spinner.start(message);
+    else {
+        process.once("SIGINT", cancel);
+        report(message);
+    }
+    try {
+        const result = await work(cancellation.signal, report);
+        cancellation.signal.throwIfAborted();
+        spinner?.stop(message);
+        return result;
+    }
+    catch (error) {
+        if (error instanceof InstallerCancelled)
+            spinner?.stop("Stopped.");
+        else
+            spinner?.error("Could not complete this step.");
+        throw error;
+    }
+    finally {
+        process.off("SIGINT", cancel);
+    }
+}
+/** No unattended operation may fall through into an interactive question. */
+export const unattendedPrompts = {
+    openBrowser: () => Promise.resolve(),
+    text: missing,
+    password: missing,
+    select: missing,
+    multiselect: missing,
+    confirm: missing,
+    note(message, title) {
+        process.stderr.write(`${title}: ${message}\n`);
+    },
+};
+function missing(message) {
+    return Promise.reject(new InstallationError("invalid_configuration", `Missing unattended input: ${message}`));
+}

package/scripts/installation/installer/run.js

@@ -0,0 +1,251 @@
+import { defaultInstallationDirectory } from "../location.js";
+import { CloudAuthorizationRequired } from "../../cloud/login.js";
+import { editInstallationSettings } from "./settings.js";
+import { registerCloudServices } from "../../cloud/registration.js";
+import { registerWithBrowser, registerUnattended } from "./cloud.js";
+import { savedSetup, prepareConfiguration, rejectNewSelections, } from "../configure.js";
+import * as clack from "@clack/prompts";
+import { styleText } from "node:util";
+import { setTimeout as delay } from "node:timers/promises";
+import { writeFile, access } from "node:fs/promises";
+import { dirname, resolve, join } from "node:path";
+import { collectInstallation } from "./collect.js";
+import { InstallerCancelled, SectionCancelled, progress, requireTerminal, terminalPrompts, unattendedPrompts, terminalLink, } from "./prompts.js";
+import { saveConfiguration } from "../save.js";
+import { planInstallation, applyInstallation } from "../plan.js";
+import { checkHost, checkNewInstallationPorts, checkInstallationPrerequisites, } from "../prerequisites.js";
+import { startInstallation, withVerifiedAdministrator } from "../lifecycle.js";
+import { administratorSetup } from "../administrator.js";
+import { InstallationError } from "../errors.js";
+const operations = {
+    plan: planInstallation,
+    host: checkHost,
+    ports: checkNewInstallationPorts,
+    prerequisites: checkInstallationPrerequisites,
+    apply: applyInstallation,
+    start: startInstallation,
+    administrator: administratorSetup,
+    register: registerCloudServices,
+};
+export async function installFromAnswers(options, ui, operator = operations, task = async (_message, work) => work(new AbortController().signal, (message) => {
+    ui.note(message, "Startup");
+})) {
+    if (options.reapply)
+        throw new InstallationError("invalid_configuration", "--reapply requires an existing installation.");
+    const saved = await savedSetup(options);
+    if (saved)
+        rejectNewSelections(options);
+    await task("Checking this machine", () => operator.host());
+    let draft;
+    while (!saved) {
+        draft = options.nonInteractive
+            ? await prepareConfiguration(options)
+            : await collectInstallation(ui, options, draft);
+        await operator.ports(draft.config.exposure);
+        if (options.nonInteractive)
+            break;
+        try {
+            if (await ui.confirm(`Install in ${draft.directory}?`, true))
+                break;
+            return { state: "cancelled" };
+        }
+        catch (error) {
+            if (!(error instanceof SectionCancelled))
+                throw error;
+        }
+    }
+    const setup = saved ??
+        (draft
+            ? {
+                configFile: await saveConfiguration(draft.directory, draft.config, draft.inputs),
+                config: draft.config,
+            }
+            : undefined);
+    if (!setup)
+        throw new InstallationError("invalid_configuration", "No installation settings were collected.");
+    const { configFile, config } = setup;
+    const directory = dirname(configFile);
+    const planFile = join(directory, "preview.json");
+    const stateDirectory = resolve(directory, config.stateDirectory);
+    try {
+        await task("Preparing required software", (signal, report) => operator.prerequisites(configFile, { acquire: true, signal, report }));
+        if (options.nonInteractive)
+            await registerUnattended(configFile, options.cloudCredentialFile, operator.register);
+        else
+            await registerWithBrowser(configFile, ui, task, operator.register);
+        const plan = await task("Checking installation settings", () => operator.plan(configFile));
+        await writeFile(planFile, JSON.stringify(plan, null, 2) + "\n", {
+            mode: 0o600,
+        });
+        await task("Installing ClawScarf", () => operator.apply(configFile, planFile));
+        if (!(options.start ??
+            (options.nonInteractive ? true : await ui.confirm("Start now?", true)))) {
+            ui.note(`clawscarf start --directory ${quote(directory)}`, "Start later");
+            return { state: "prepared", directory };
+        }
+        const started = await task("Starting ClawScarf", (signal, report) => operator.start(stateDirectory, report, signal));
+        const administrator = await finishAdministrator(stateDirectory, options, ui, task, operator.administrator, true);
+        if (administrator)
+            return {
+                state: "action_required",
+                ready: false,
+                ...administrator,
+                directory,
+                resume: `clawscarf status --directory ${quote(directory)} --json`,
+            };
+        const origin = config.exposure.mode === "https"
+            ? config.exposure.applicationOrigin
+            : `http://127.0.0.1:${String(config.exposure.applicationPort)}`;
+        return {
+            ...withVerifiedAdministrator(started),
+            directory,
+            applicationUrl: origin,
+        };
+    }
+    catch (error) {
+        if (error instanceof CloudAuthorizationRequired)
+            return {
+                state: "action_required",
+                action: "cloud_authorization",
+                ...error.action,
+                directory,
+                resume: `clawscarf configure --directory ${quote(directory)} --non-interactive${options.start === false ? " --no-start" : ""} --json`,
+            };
+        if (error instanceof InstallerCancelled ||
+            error instanceof SectionCancelled)
+            throw error;
+        ui.note(`Resume: clawscarf configure --directory ${quote(directory)}\nStatus: clawscarf status --directory ${quote(directory)}\nLogs: clawscarf logs --directory ${quote(directory)} --service controller\nThe server, if started, keeps running. No failed operation is automatically repeated.`, "Installation needs attention");
+        throw error;
+    }
+}
+async function finishAdministrator(state, options, ui, task, administrator = administratorSetup, verify = false) {
+    const current = await task("Verifying administrator access", () => administrator(state, false, verify));
+    if (current.complete)
+        return undefined;
+    if (options.nonInteractive)
+        return {
+            action: "administrator_sign_in",
+            ...(await administrator(state, true)),
+        };
+    await browserSignIn(ui, task, () => administrator(state, true), () => administrator(state));
+    return undefined;
+}
+async function browserSignIn(ui, task, issue, observe) {
+    for (;;) {
+        const link = await issue();
+        if (!link.url || !link.expiresAt)
+            throw new InstallationError("unavailable", "Administrator setup did not return a login link.");
+        ui.note(`ClawScarf has started. Open this private link in your browser to sign in, then return here.\n\n${terminalLink(link.url)}\n\nExpires at ${link.expiresAt}.`, styleText(["bold", "yellow"], "ACTION REQUIRED — Administrator sign-in"));
+        await ui.openBrowser(link.url);
+        const complete = await task("Waiting for administrator sign-in", async (signal) => {
+            for (;;) {
+                signal.throwIfAborted();
+                const status = await observe();
+                if (status.complete)
+                    return true;
+                if (!status.expiresAt || Date.now() >= Date.parse(status.expiresAt))
+                    return false;
+                await delay(3000, undefined, { signal }).catch((error) => {
+                    signal.throwIfAborted();
+                    throw error;
+                });
+            }
+        });
+        if (complete)
+            return;
+        if (!(await ui.confirm("Login link expired. Create a new link?", true)))
+            throw new InstallerCancelled();
+    }
+}
+function quote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+/** The command selects the workflow; users never manipulate preparation files. */
+export async function runConfiguration(options) {
+    options = {
+        ...options,
+        directory: options.directory ?? defaultInstallationDirectory,
+    };
+    if (options.json && !options.nonInteractive)
+        throw new InstallationError("invalid_configuration", "Use --non-interactive with --json.");
+    if (!options.nonInteractive) {
+        requireTerminal();
+        clack.intro("ClawScarf — protected OpenClaw for your team");
+    }
+    const ui = options.nonInteractive ? unattendedPrompts : terminalPrompts;
+    try {
+        if (options.reapply)
+            throw new InstallationError("invalid_configuration", "--reapply requires an existing installation.");
+        const saved = await savedSetup(options);
+        const state = saved
+            ? resolve(dirname(saved.configFile), saved.config.stateDirectory)
+            : undefined;
+        let existing = false;
+        if (state) {
+            try {
+                await access(join(state, "settings.json"));
+                existing = true;
+            }
+            catch (error) {
+                if (!(error instanceof Error &&
+                    "code" in error &&
+                    error.code === "ENOENT"))
+                    throw error;
+            }
+        }
+        let result = existing && state
+            ? await editInstallationSettings(state, ui, options)
+            : await installFromAnswers(options, ui, operations, (message, work) => progress(message, work, options));
+        if (existing && state && "services" in result) {
+            const administrator = await finishAdministrator(state, options, ui, (message, work) => progress(message, work, options));
+            if (administrator)
+                return {
+                    state: "action_required",
+                    ready: false,
+                    ...administrator,
+                    directory: options.directory,
+                    resume: `clawscarf status --directory ${quote(resolve(options.directory ?? "."))} --json`,
+                };
+            result = withVerifiedAdministrator(result);
+        }
+        if (!options.nonInteractive) {
+            const applicationUrl = "applicationUrl" in result && typeof result.applicationUrl === "string"
+                ? result.applicationUrl
+                : saved
+                    ? saved.config.exposure.mode === "https"
+                        ? saved.config.exposure.applicationOrigin
+                        : `http://127.0.0.1:${String(saved.config.exposure.applicationPort)}`
+                    : undefined;
+            if (result.state === "cancelled")
+                clack.cancel("Cancelled.");
+            else
+                clack.outro("ready" in result
+                    ? result.ready
+                        ? `ClawScarf is ready.${applicationUrl ? ` Visit ${terminalLink(applicationUrl)}` : ""}\n\nManage this installation:\n  clawscarf status --directory ${quote(options.directory ?? defaultInstallationDirectory)}\n  clawscarf stop --directory ${quote(options.directory ?? defaultInstallationDirectory)}`
+                        : "ClawScarf needs attention. Check status for details."
+                    : result.state === "unchanged"
+                        ? "No changes. Server left as it was."
+                        : "Configuration saved. Server stopped.");
+            if ("ready" in result && result.ready && applicationUrl)
+                await ui.openBrowser(applicationUrl);
+        }
+        return result;
+    }
+    catch (error) {
+        if (error instanceof CloudAuthorizationRequired)
+            return {
+                state: "action_required",
+                action: "cloud_authorization",
+                ...error.action,
+                directory: options.directory,
+                resume: `clawscarf configure --directory ${quote(resolve(options.directory ?? "."))} --non-interactive --yes${options.start === false ? " --no-start" : ""} --json`,
+            };
+        if (!(error instanceof InstallerCancelled) &&
+            !(error instanceof SectionCancelled))
+            throw error;
+        if (!options.nonInteractive)
+            clack.cancel("Exited. Saved files and any running installation are retained.");
+        process.exitCode = 130;
+        return { state: "cancelled" };
+    }
+}

package/scripts/installation/installer/secrets.js

@@ -0,0 +1,16 @@
+import { InstallationError } from "../errors.js";
+import { inputFile } from "./inputs.js";
+export async function secretInput(ui, inputs, message, name, current) {
+    const mode = await ui.select(message, [
+        ...(current ? [{ value: "keep", label: "Keep current value" }] : []),
+        { value: "paste", label: "Paste secret (hidden)" },
+        { value: "file", label: "Import private file" },
+    ], current ? "keep" : "paste");
+    if (mode === "keep" && current)
+        return current;
+    if (mode === "file")
+        return inputFile(ui, `${message} file`, true);
+    if (mode !== "paste")
+        throw new InstallationError("invalid_configuration", "Select a secret input method.");
+    return inputs.set(name, await ui.password(message));
+}

package/scripts/installation/installer/sections/access.js

@@ -0,0 +1,69 @@
+import { defaultCloudUrl } from "../../../cloud/url.js";
+import { z } from "zod";
+import { field, inputFile } from "../inputs.js";
+export async function collectAccess(ui, current, cloudUrl = defaultCloudUrl) {
+    const custom = await ui.confirm("Use your own OIDC provider?", current.access.mode === "oidc");
+    if (!custom)
+        return {
+            access: {
+                mode: "hosted",
+                administratorName: current.access.administratorName,
+                registrationFile: "./secrets/hosted-login.json",
+                cloudUrl: current.access.mode === "hosted" ? current.access.cloudUrl : cloudUrl,
+            },
+        };
+    const previous = current.access.mode === "oidc" ? current.access : undefined;
+    const origin = current.exposure.mode === "https"
+        ? current.exposure.applicationOrigin
+        : `http://127.0.0.1:${String(current.exposure.applicationPort)}`;
+    ui.note(`Callback: ${origin}/_clawscarf/callback\nAfter logout: ${origin}/_clawscarf/signed-out`, "OIDC application URLs");
+    const issuer = await field(ui, "OIDC issuer", z.url(), previous?.issuer);
+    const clientId = await ui.text("OIDC client ID", previous?.clientId);
+    return {
+        access: {
+            mode: "oidc",
+            administratorName: current.access.administratorName,
+            issuer,
+            clientId,
+            clientSecretFile: previous?.issuer === issuer && previous.clientId === clientId
+                ? previous.clientSecretFile
+                : "",
+            ...(previous?.issuer === issuer &&
+                previous.clientId === clientId &&
+                previous.administratorSubject &&
+                previous.administratorEmail
+                ? {
+                    administratorSubject: previous.administratorSubject,
+                    administratorEmail: previous.administratorEmail,
+                }
+                : {}),
+        },
+    };
+}
+export async function collectExposure(ui, current) {
+    const network = await ui.confirm("Make this server available over HTTPS?", current.exposure.mode === "https");
+    if (!network) {
+        const port = z
+            .string()
+            .regex(/^\d+$/)
+            .refine((value) => Number(value) >= 1024 && Number(value) <= 65535, "Use a port from 1024 to 65535.");
+        const previous = current.exposure.mode === "local" ? current.exposure : undefined;
+        const applicationPort = Number(await field(ui, "Application port", port, String(previous?.applicationPort ?? 18800)));
+        const widgetPort = Number(await field(ui, "Widgets port", port.refine((value) => Number(value) !== applicationPort, "Use a different port."), String(previous?.widgetPort ?? 18802)));
+        return { mode: "local", applicationPort, widgetPort };
+    }
+    const previous = current.exposure.mode === "https" ? current.exposure : undefined;
+    const origin = z
+        .url()
+        .refine((value) => new URL(value).origin === value && new URL(value).protocol === "https:", "Use an HTTPS origin.");
+    const applicationOrigin = await field(ui, "Application HTTPS origin", origin, previous?.applicationOrigin);
+    const widgetOrigin = await field(ui, "Widgets HTTPS origin", origin.refine((value) => new URL(value).port !== new URL(applicationOrigin).port, "Use distinct listener ports."), previous?.widgetOrigin);
+    const certificateFile = await inputFile(ui, "TLS certificate file", false, previous?.certificateFile);
+    return {
+        mode: "https",
+        applicationOrigin,
+        widgetOrigin,
+        certificateFile,
+        keyFile: previous?.certificateFile === certificateFile ? previous.keyFile : "",
+    };
+}

package/scripts/installation/installer/sections/certificates.js

@@ -0,0 +1,18 @@
+import { inputFile } from "../inputs.js";
+export async function optionalCa(ui, current) {
+    if (current) {
+        const action = await ui.select("Certificate authority", [
+            { value: "keep", label: "Keep custom certificate authority" },
+            { value: "replace", label: "Replace certificate authority" },
+            { value: "system", label: "Use system certificate authorities" },
+        ], "keep");
+        if (action === "keep")
+            return { caFile: current };
+        if (action === "system")
+            return {};
+        return { caFile: await inputFile(ui, "CA certificate file") };
+    }
+    return (await ui.confirm("Use a custom certificate authority?"))
+        ? { caFile: await inputFile(ui, "CA certificate file") }
+        : {};
+}

package/scripts/installation/installer/sections/connections.js

@@ -0,0 +1,4 @@
+export async function collectConnections(ui, current) {
+    const enabled = await ui.confirm("Enable Connections?", current.mode !== "disabled");
+    return { ...current, mode: enabled ? "hosted" : "disabled" };
+}

package/scripts/installation/installer/sections/external-models.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { configurationSchema, gatewayRoutesSchema, } from "../../../models/configuration.js";
+import { InstallationError } from "../../errors.js";
+import { field } from "../inputs.js";
+import { optionalCa } from "./certificates.js";
+export async function collectExternalModels(ui, inputs, file, current) {
+    const catalog = z
+        .union([gatewayRoutesSchema, configurationSchema])
+        .parse(await inputs.readJson(file));
+    if ("mode" in catalog && catalog.mode === "disabled")
+        throw new InstallationError("invalid_configuration", "LiteLLM requires an enabled model catalog.");
+    const baseUrl = await field(ui, "LiteLLM API URL (ending in /v1)", z.url(), "baseUrl" in catalog ? catalog.baseUrl : undefined);
+    const config = configurationSchema.parse({
+        mode: "external",
+        baseUrl,
+        models: catalog.models,
+        defaultModel: catalog.defaultModel,
+        ...(catalog.thinkingDefault
+            ? { thinkingDefault: catalog.thinkingDefault }
+            : {}),
+    });
+    const previous = current?.mode === "external"
+        ? configurationSchema.parse(await inputs.readJson(current.configurationFile))
+        : undefined;
+    return {
+        mode: "external",
+        configurationFile: inputs.set("external-models.json", JSON.stringify(config, null, 2)),
+        credentialFile: current?.mode === "external" &&
+            previous?.mode === "external" &&
+            previous.baseUrl === baseUrl
+            ? current.credentialFile
+            : "",
+        ...(await optionalCa(ui, current?.mode === "external" ? current.caFile : undefined)),
+    };
+}