@clawscarf/cli 0.1.0-alpha.1

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

@@ -0,0 +1,119 @@
+import { selectModel } from "../../models.js";
+import { gatewayRoutesSchema, configurationSchema, } from "../../../models/configuration.js";
+import { secretInput } from "../secrets.js";
+import { inputFile } from "../inputs.js";
+import { InstallationError } from "../../errors.js";
+export async function modelRoutes(file, inputs) {
+    return gatewayRoutesSchema.parse(await inputs.readJson(file));
+}
+export function providerLabel(route) {
+    const name = route.model.split("/")[0] ?? "Provider";
+    return ({
+        openrouter: "OpenRouter",
+        openai: "OpenAI",
+        anthropic: "Anthropic",
+        gemini: "Google",
+    }[name] ?? name);
+}
+/** Settings only. Credentials are collected after the complete installation review. */
+export async function collectModels(ui, offers, current, inputs, presetFile, retainModels = false) {
+    if (current?.mode === "external") {
+        const catalog = configurationSchema.parse(await inputs.readJson(current.configurationFile));
+        if (catalog.mode !== "external")
+            throw new InstallationError("invalid_configuration", "Import the existing gateway's model catalog under Advanced.");
+        const defaultModel = await ui.select("Default model", catalog.models
+            .filter((model) => model.enabled)
+            .map((model) => ({ value: model.id, label: model.name })), catalog.defaultModel ?? undefined);
+        const model = catalog.models.find((model) => model.id === defaultModel);
+        const thinkingDefault = model?.reasoning
+            ? await ui.select("Reasoning", ["low", "medium", "high"].map((value) => ({ value, label: value })), catalog.thinkingDefault ?? "medium")
+            : undefined;
+        const { thinkingDefault: _previous, ...base } = catalog;
+        return {
+            ...current,
+            configurationFile: inputs.set("external-models.json", JSON.stringify({
+                ...base,
+                defaultModel,
+                ...(thinkingDefault ? { thinkingDefault } : {}),
+            })),
+        };
+    }
+    const file = current?.configurationFile ?? presetFile;
+    const routes = file ? await modelRoutes(file, inputs) : undefined;
+    const choices = new Map([
+        ...offers.map((offer) => [offer.model.id, offer.model.name]),
+        ...(routes?.models.map((model) => [model.id, model.name]) ?? []),
+    ]);
+    if (!choices.size)
+        throw new InstallationError("invalid_configuration", "No model choices are available. Import a catalog under Advanced.");
+    const id = await ui.select("Default model", [...choices].map(([value, label]) => ({ value, label })), routes?.defaultModel);
+    const existing = routes?.models.find((model) => model.id === id);
+    const matching = offers.filter((offer) => offer.model.id === id);
+    const providerOptions = new Map(matching.map((offer) => [offer.model.route.model, offer]));
+    if (existing?.route && !providerOptions.has(existing.route.model))
+        providerOptions.set(existing.route.model, {
+            provider: providerLabel(existing.route),
+            model: { ...existing, route: existing.route },
+            reasoningLevels: existing.reasoning ? ["low", "medium", "high"] : [],
+        });
+    if (!providerOptions.size)
+        throw new InstallationError("invalid_configuration", "This model has no configured provider. Choose another model or import a catalog under Advanced.");
+    const selectedRoute = await ui.select("Provider", [...providerOptions].map(([value, offer]) => ({
+        value,
+        label: offer.provider,
+    })), existing?.route?.model);
+    const offer = providerOptions.get(selectedRoute);
+    if (!offer?.model.route)
+        throw new InstallationError("invalid_configuration", "Select a supported provider route.");
+    const thinkingDefault = offer.reasoningLevels.length
+        ? await ui.select("Reasoning", offer.reasoningLevels.map((value) => ({
+            value,
+            label: value.charAt(0).toUpperCase() + value.slice(1),
+        })), routes?.thinkingDefault &&
+            offer.reasoningLevels.includes(routes.thinkingDefault)
+            ? routes.thinkingDefault
+            : offer.reasoningLevels.includes("medium")
+                ? "medium"
+                : offer.reasoningLevels[0])
+        : undefined;
+    return selectModel(current, routes, offer, thinkingDefault, inputs, retainModels);
+}
+export async function collectModelCredentials(ui, current, inputs) {
+    if (current.mode === "external")
+        return current.credentialFile
+            ? current
+            : {
+                ...current,
+                credentialFile: await secretInput(ui, inputs, "Model gateway key", "model-key"),
+            };
+    if (current.upstreamEnvironmentFile)
+        return current;
+    const routes = await modelRoutes(current.configurationFile, inputs);
+    const selected = routes.models.find((model) => model.id === routes.defaultModel);
+    ui.note(`${selected?.name ?? routes.defaultModel}${routes.thinkingDefault ? " · " + routes.thinkingDefault : ""}\nProvider: ${selected?.route ? providerLabel(selected.route) : "Custom"}`, "LLM credentials");
+    const mode = await ui.select("LLM API keys", [
+        { value: "paste", label: "Enter keys (hidden)" },
+        { value: "file", label: "Import private credentials file" },
+    ], "paste");
+    if (mode === "file")
+        return {
+            ...current,
+            upstreamEnvironmentFile: await inputFile(ui, "Provider credentials file (.env)", true),
+        };
+    const values = new Map();
+    for (const model of routes.models.filter((item) => item.enabled)) {
+        const route = model.route;
+        if (!route)
+            throw new InstallationError("invalid_configuration", "An enabled model has no provider route.");
+        if (values.has(route.apiKeyEnv))
+            continue;
+        const key = await ui.password(`${providerLabel(route)} LLM API key`);
+        if (!key.trim() || /[\r\n'"`]/.test(key))
+            throw new InstallationError("invalid_configuration", "Use a single-line provider key without quote characters, or import its credentials file.");
+        values.set(route.apiKeyEnv, key);
+    }
+    return {
+        ...current,
+        upstreamEnvironmentFile: inputs.set("models.env", [...values].map(([name, key]) => `${name}='${key}'`).join("\n") + "\n"),
+    };
+}

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

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { absolute, inputFile } from "../inputs.js";
+import { openPack } from "../../../packs/source.js";
+export async function collectPacks(ui, models, connections, current, available = []) {
+    const packs = structuredClone(current.packs);
+    let keep = false;
+    if (packs.length) {
+        const action = await ui.select("Existing packs", [
+            { value: "keep", label: "Keep selections" },
+            { value: "add", label: "Add a pack" },
+            { value: "remove", label: "Remove selected packs" },
+        ]);
+        keep = action === "keep";
+        if (action === "remove") {
+            const removed = await ui.multiselect("Remove packs", packs.map((pack, index) => ({
+                value: String(index),
+                label: pack.members.join(", "),
+            })));
+            const retained = packs.filter((_pack, index) => !removed.includes(String(index)));
+            return retained.length
+                ? {
+                    packs: retained,
+                    ...(current.packOperator
+                        ? { packOperator: current.packOperator }
+                        : {}),
+                }
+                : { packs: [] };
+        }
+    }
+    const selected = new Set(packs.flatMap((pack) => pack.members));
+    while (!keep &&
+        packs.length < 32 &&
+        (await ui.confirm(packs.length
+            ? "Add another pack?"
+            : "Install a pack? (experimental native Claws)"))) {
+        const directory = available.length
+            ? await ui.select("Pack", available.map((pack) => ({ value: pack.directory, label: pack.id })))
+            : absolute(await ui.text("Pack directory"));
+        const pack = await openPack(directory);
+        const eligible = pack.manifest.members.filter((member) => !selected.has(member.id) &&
+            (member.requirements.model === "none" || Boolean(models)) &&
+            (!member.requirements.connections.length ||
+                connections.mode !== "disabled"));
+        if (!eligible.length) {
+            ui.note("No unselected members meet the model and Connections prerequisites. Choose another pack or configure its prerequisites first.", "Pack unavailable");
+            continue;
+        }
+        const members = z
+            .array(z.enum(eligible.map((member) => member.id)))
+            .min(1)
+            .parse(await ui.multiselect("Pack agents", eligible.map((member) => ({ value: member.id, label: member.id }))));
+        const needsConnections = eligible.some((member) => members.includes(member.id) && member.requirements.connections.length);
+        const bindingsFile = needsConnections
+            ? await inputFile(ui, "Connected-account bindings file", true)
+            : undefined;
+        packs.push({
+            directory,
+            members,
+            ...(bindingsFile ? { bindingsFile } : {}),
+        });
+        members.forEach((member) => selected.add(member));
+    }
+    return collectPackInputs(ui, { ...current, packs });
+}
+export async function collectPackInputs(ui, current) {
+    const packs = structuredClone(current.packs);
+    if (!packs.length)
+        return { packs };
+    for (const selection of packs) {
+        const pack = await openPack(selection.directory);
+        if (!selection.bindingsFile &&
+            pack.manifest.members.some((member) => selection.members.includes(member.id) &&
+                member.requirements.connections.length))
+            selection.bindingsFile = await inputFile(ui, "Connected-account bindings file", true);
+    }
+    const pythonExecutable = current.packOperator?.pythonExecutable ??
+        absolute(await ui.text("Python executable with the pinned OpenShell SDK", current.packOperator?.pythonExecutable));
+    return {
+        packs,
+        packOperator: { pythonExecutable, experimentalClaws: true },
+    };
+}

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

@@ -0,0 +1,10 @@
+import { localInput } from "../../../deployment/configuration.js";
+import { field } from "../inputs.js";
+export async function collectResources(ui, current) {
+    return {
+        runtime: {
+            cpu: await field(ui, "Runtime CPUs", localInput.shape.cpu, current.runtime.cpu),
+            memory: await field(ui, "Runtime memory", localInput.shape.memory, current.runtime.memory),
+        },
+    };
+}

package/scripts/installation/installer/settings.js

@@ -0,0 +1,192 @@
+import { checkHost, checkInstallationPrerequisites } from "../prerequisites.js";
+import { z } from "zod";
+import { selectedDraft } from "../options.js";
+import { setupContext } from "../setup.js";
+import { configurationChanges, resolveConfigurationInputs, validateSelections, } from "../configure.js";
+import { registerWithBrowser, registerUnattended } from "./cloud.js";
+import { randomUUID } from "node:crypto";
+import { rm, readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { collectInstallation } from "./collect.js";
+import { progress } from "./prompts.js";
+import { SetupInputs, saveConfiguration } from "../save.js";
+import { readJson } from "../files.js";
+import { installationSchema } from "../configuration.js";
+import { planSettingsChange, reconfigureInstallation } from "../reconfigure.js";
+import { controlInstallation, startInstallation } from "../lifecycle.js";
+import { InstallationError } from "../errors.js";
+import { withInstallationLock, writePrivate } from "../../deployment/state.js";
+/** The menu only gathers answers; the same plan/apply operations serve unattended callers. */
+export async function editInstallationSettings(directory, ui, options = {}, prerequisites = { host: checkHost, check: checkInstallationPrerequisites }) {
+    directory = resolve(directory);
+    if (options.recipe || options.cloudUrl)
+        throw new InstallationError("change_unsupported", "Existing installations keep their recipe, software release and login service. Change models, keys, Connections or packs instead.");
+    if (options.nonInteractive && !options.yes)
+        throw new InstallationError("invalid_configuration", "Changing an existing installation noninteractively requires --yes. The server may restart and deselected packs may be removed.");
+    const task = (message, work) => progress(message, work, options);
+    const settingsFile = join(directory, "settings.json");
+    const before = await readFile(settingsFile, "utf8");
+    const config = installationSchema.parse(JSON.parse(before));
+    const record = z
+        .object({
+        settingsCandidate: z.string().optional(),
+        settingsReapply: z.enum(["models", "connections"]).optional(),
+    })
+        .parse(await readJson(join(directory, "prepared.json")));
+    const pending = record.settingsCandidate;
+    if (record.settingsReapply &&
+        options.reapply &&
+        record.settingsReapply !== options.reapply)
+        throw new InstallationError("change_unsupported", "Resume the pending change before selecting another capability.");
+    const reapply = options.reapply ?? record.settingsReapply;
+    if (pending &&
+        (dirname(dirname(pending)) !== directory ||
+            !/^\.settings-[a-f0-9-]+$/u.test(dirname(pending).slice(directory.length + 1))))
+        throw new InstallationError("invalid_configuration", "The pending configuration does not belong to this installation.");
+    const staging = pending
+        ? dirname(pending)
+        : join(directory, `.settings-${randomUUID()}`);
+    const inputs = new SetupInputs(staging);
+    let attempted = false;
+    let authorizing;
+    let retained = Boolean(pending);
+    try {
+        const context = await setupContext({}, config.releaseFile);
+        const selected = await selectedDraft(context, config.recipe?.id ?? "custom", options, inputs, config);
+        if (pending && JSON.stringify(selected) !== JSON.stringify(config))
+            throw new InstallationError("change_unsupported", "Resume the interrupted configuration without new selections first.");
+        const draft = pending
+            ? undefined
+            : options.nonInteractive
+                ? { config: await validateSelections(context, selected) }
+                : await collectInstallation(ui, { existing: true }, { directory: staging, config: selected, inputs });
+        if ((await readFile(settingsFile, "utf8")) !== before)
+            throw new InstallationError("stale_plan", "Settings changed while this menu was open. Reopen it before applying.");
+        const candidate = pending ??
+            (await saveConfiguration(staging, installationSchema.parse(draft?.config), inputs, true));
+        if (pending &&
+            !options.nonInteractive &&
+            !(await ui.confirm("Resume this interrupted change?"))) {
+            await withInstallationLock(directory, async () => {
+                const prepared = z
+                    .object({
+                    ownerId: z.string(),
+                    settingsCandidate: z.string().optional(),
+                    settingsReapply: z.enum(["models", "connections"]).optional(),
+                    settingsPending: z.string().optional(),
+                })
+                    .parse(await readJson(join(directory, "prepared.json")));
+                if (prepared.settingsCandidate !== pending)
+                    throw new InstallationError("stale_plan", "The pending change has changed. Reopen configure.");
+                if (!prepared.settingsPending) {
+                    await writePrivate(join(directory, "prepared.json"), JSON.stringify({ ownerId: prepared.ownerId }));
+                    retained = false;
+                }
+            });
+            return { state: "cancelled" };
+        }
+        if (!pending &&
+            !reapply &&
+            !Object.values(await configurationChanges(config, resolveConfigurationInputs(installationSchema.parse(await readJson(candidate)), dirname(candidate)))).some(Boolean))
+            return { state: "unchanged" };
+        await task("Checking this machine", () => prerequisites.host());
+        await task("Preparing required software", (signal, report) => prerequisites.check(candidate, {
+            acquire: true,
+            signal,
+            report,
+        }));
+        authorizing = candidate;
+        if (options.nonInteractive)
+            await registerUnattended(candidate, options.cloudCredentialFile);
+        else
+            await registerWithBrowser(candidate, ui, task);
+        authorizing = undefined;
+        const plan = await planSettingsChange(candidate, reapply);
+        ui.note([
+            ...(plan.scopes.models && plan.changes.models
+                ? [
+                    `Model: ${plan.changes.models.default ?? "None"} · ${plan.changes.models.reasoning}`,
+                ]
+                : []),
+            ...(plan.scopes.connections
+                ? [
+                    `Connections: ${plan.changes.connections.to === "disabled" ? "Off" : "On"}`,
+                ]
+                : []),
+            ...(plan.scopes.packs
+                ? [`Packs: ${plan.changes.packs.selected.join(", ") || "None"}`]
+                : []),
+            ...(plan.changes.packs.removed.length
+                ? [
+                    `Remove pack agents and native-owned data: ${plan.changes.packs.removed.join(", ")}`,
+                ]
+                : []),
+            "The server will stop to apply these changes.",
+        ].join("\n"), "Review change");
+        if (!pending &&
+            !options.nonInteractive &&
+            !(await ui.confirm("Apply these settings?")))
+            return { state: "cancelled" };
+        attempted = true;
+        const current = await controlInstallation(directory, "status");
+        if (current.state !== "stopped") {
+            await task("Stopping ClawScarf", async (signal) => {
+                await controlInstallation(directory, "stop");
+                const deadline = Date.now() + 120_000;
+                while ((await controlInstallation(directory, "status")).state !== "stopped") {
+                    if (Date.now() >= deadline)
+                        throw new InstallationError("unavailable", "Shutdown is not yet confirmed. Check status before applying settings.");
+                    await delay(500, undefined, { signal });
+                }
+            });
+        }
+        await task("Applying settings", () => reconfigureInstallation(candidate, plan.fingerprint, reapply));
+        // Only our preceding accepted menu draft is retired. Never remove user-supplied inputs.
+        const previousInputs = dirname(config.models.configurationFile);
+        if (previousInputs !== staging &&
+            dirname(previousInputs) === directory &&
+            /^\.settings-[a-f0-9-]+$/u.test(previousInputs.slice(directory.length + 1)))
+            await rm(previousInputs, { recursive: true });
+        if (options.start ??
+            (options.nonInteractive
+                ? true
+                : await ui.confirm("Start with these settings?", true))) {
+            return await task("Starting ClawScarf", (signal, report) => startInstallation(directory, report, signal));
+        }
+        ui.note(`clawscarf start --directory '${resolve(options.directory ?? dirname(directory)).replaceAll("'", "'\\''")}'`, "Start later");
+        return { state: "prepared" };
+    }
+    catch (error) {
+        if (authorizing && !pending) {
+            const candidate = authorizing;
+            await withInstallationLock(directory, async () => {
+                if ((await readFile(settingsFile, "utf8")) !== before)
+                    throw new InstallationError("stale_plan", "Settings changed during authorization. Reopen configure before applying.");
+                const prepared = z
+                    .object({
+                    ownerId: z.string(),
+                    settingsCandidate: z.string().optional(),
+                    settingsReapply: z.enum(["models", "connections"]).optional(),
+                    settingsPending: z.string().optional(),
+                })
+                    .parse(await readJson(join(directory, "prepared.json")));
+                if (prepared.settingsCandidate || prepared.settingsPending)
+                    throw new InstallationError("stale_plan", "Another configuration is pending. Resume it before applying these settings.");
+                await writePrivate(join(directory, "prepared.json"), JSON.stringify({
+                    ...prepared,
+                    settingsCandidate: candidate,
+                    ...(reapply ? { settingsReapply: reapply } : {}),
+                }));
+                retained = true;
+            });
+        }
+        if (attempted)
+            ui.note("Check status, then run configure --directory again to review and resume the interrupted change.", "Retained settings");
+        throw error;
+    }
+    finally {
+        if (!attempted && !retained)
+            await rm(staging, { recursive: true, force: true });
+    }
+}

package/scripts/installation/installer/summary.js

@@ -0,0 +1,44 @@
+import { inputErrorMessage } from "./inputs.js";
+import { providerLabel } from "./sections/models.js";
+import { z } from "zod";
+import { gatewayRoutesSchema } from "../../models/configuration.js";
+import { readJson } from "../files.js";
+export async function modelSummary(config, inputs) {
+    let model = "Provider credentials needed";
+    if (config.models) {
+        const placement = config.models.mode === "litellm" ? "Provider" : "Existing model gateway";
+        try {
+            const value = inputs
+                ? await inputs.readJson(config.models.configurationFile)
+                : await readJson(config.models.configurationFile);
+            const catalog = z
+                .object({
+                models: gatewayRoutesSchema.shape.models,
+                defaultModel: z.string().nullable(),
+                thinkingDefault: gatewayRoutesSchema.shape.thinkingDefault,
+            })
+                .parse(value);
+            const selected = catalog.models.find((entry) => entry.id === catalog.defaultModel);
+            model = `${selected?.route ? providerLabel(selected.route) : placement} · ${selected?.name ?? "No default"}${catalog.thinkingDefault ? ` · ${catalog.thinkingDefault}` : ""}`;
+        }
+        catch (error) {
+            if (!inputErrorMessage(error))
+                throw error;
+            model = `${placement} · Check model catalog`;
+        }
+    }
+    return model;
+}
+export async function installationSummary(config, inputs) {
+    const model = await modelSummary(config, inputs);
+    const origin = config.exposure.mode === "local"
+        ? `http://127.0.0.1:${String(config.exposure.applicationPort)}`
+        : config.exposure.applicationOrigin;
+    return [
+        `${config.name} — ${origin}`,
+        `Administrator: ${config.access.administratorName} · ${config.access.mode === "hosted" ? "ClawScarf login" : "Custom OIDC"}`,
+        `Models: ${model}`,
+        `Connections: ${config.connections.mode === "disabled" ? "Off" : "On"}`,
+        `Browser: ${config.browser.enabled ? "Experimental" : "Off"} · Packs: ${config.packs.flatMap((pack) => pack.members).join(", ") || "None"}`,
+    ].join("\n");
+}

package/scripts/installation/lifecycle.js

@@ -0,0 +1,127 @@
+import { checkHost, checkInstallationPrerequisites } from "./prerequisites.js";
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { z } from "zod";
+import { administratorSetup } from "./administrator.js";
+import { launchLocal, stopLocal } from "../deployment/launch.js";
+import { compose } from "../deployment/compose.js";
+import { readState, resourceNames, withInstallationLock, } from "../deployment/state.js";
+import { run } from "../deployment/process.js";
+import { localLogNames } from "../deployment/logs.js";
+import { InstallationError } from "./errors.js";
+import { activatePacks, packOutcomeSchema } from "./packs.js";
+const containerSchema = z.object({
+    Service: z.string(),
+    State: z.string(),
+    Health: z.string().optional(),
+});
+/** No daemon or cached readiness: observe Docker and the live Access endpoint. */
+async function installationStatus(directory) {
+    const state = await readState(directory);
+    const rows = (await compose(directory, ["ps", "--all", "--format", "json"]))
+        .trim()
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => containerSchema.parse(JSON.parse(line)));
+    const expected = (await compose(directory, ["config", "--services"]))
+        .trim()
+        .split("\n");
+    const containers = rows.map((row) => ({
+        service: row.Service,
+        state: row.State,
+        ...(row.Health ? { health: row.Health } : {}),
+    }));
+    const sandboxRows = z
+        .array(z.object({ State: z.string() }))
+        .parse(JSON.parse(await run("docker", [
+        "container",
+        "ls",
+        "--all",
+        "--format",
+        "json",
+        "--filter",
+        `label=openshell.ai/sandbox-namespace=${resourceNames(state).sandbox}`,
+    ]).then((output) => "[" + output.trim().split("\n").filter(Boolean).join(",") + "]")));
+    const running = rows.some((row) => ["running", "restarting", "paused"].includes(row.State)) ||
+        sandboxRows.some((row) => ["running", "restarting", "paused"].includes(row.State));
+    const containersReady = sandboxRows.length === 1 &&
+        sandboxRows.every((row) => row.State === "running") &&
+        expected.every((name) => rows.some((row) => row.Service === name &&
+            row.State === "running" &&
+            (!row.Health || row.Health === "healthy")));
+    const servicesReady = containersReady &&
+        (await fetch(`http://127.0.0.1:${String(state.input.ports.native)}/healthz`, { signal: AbortSignal.timeout(3000) }).then(async (response) => {
+            await response.body?.cancel();
+            return response.ok;
+        }, () => false));
+    const administrator = servicesReady
+        ? await administratorSetup(directory).then((setup) => (setup.complete ? "ready" : "pending"), () => "unavailable")
+        : "unavailable";
+    let packs = [];
+    try {
+        packs = z
+            .array(packOutcomeSchema)
+            .parse(JSON.parse(await readFile(join(directory, "pack-status.json"), "utf8")));
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            throw error;
+    }
+    return {
+        state: !running
+            ? "stopped"
+            : servicesReady && administrator !== "unavailable"
+                ? "running"
+                : "degraded",
+        ready: servicesReady &&
+            administrator === "ready" &&
+            packs.every((pack) => pack.state === "complete"),
+        administrator,
+        packs,
+        services: containers,
+    };
+}
+export async function startInstallation(directory, report, signal) {
+    directory = resolve(directory);
+    return withInstallationLock(directory, async () => {
+        const state = await readState(directory);
+        if (!state.input.modelGateway && !state.input.models)
+            throw new InstallationError("invalid_configuration", "Bundled or existing LiteLLM is required.");
+        await checkHost();
+        await checkInstallationPrerequisites(join(directory, "settings.json"), {
+            acquire: true,
+            report,
+            ...(signal ? { signal } : {}),
+        });
+        await launchLocal(directory, report, {
+            activate: async () => {
+                await activatePacks(directory, report);
+            },
+        });
+        return installationStatus(directory);
+    });
+}
+export async function controlInstallation(directory, action) {
+    directory = resolve(directory);
+    await readState(directory);
+    if (action === "stop")
+        await withInstallationLock(directory, async () => {
+            if ((await installationStatus(directory)).state !== "stopped")
+                await stopLocal(directory);
+        });
+    return installationStatus(directory);
+}
+export async function installationLogs(directory, service) {
+    await readState(resolve(directory));
+    const name = z.enum(localLogNames).parse(service);
+    return compose(directory, ["logs", "--no-color", "--tail", "100", name]);
+}
+/** Administrator verification completes setup; it cannot make failed services or packs ready. */
+export function withVerifiedAdministrator(status) {
+    return {
+        ...status,
+        administrator: "ready",
+        ready: status.state === "running" &&
+            status.packs.every((pack) => pack.state === "complete"),
+    };
+}

package/scripts/installation/location.js

@@ -0,0 +1,3 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const defaultInstallationDirectory = join(homedir(), "clawscarf-team");

package/scripts/installation/models.js

@@ -0,0 +1,42 @@
+import { InstallationError } from "./errors.js";
+import { gatewayRoutesSchema } from "../models/configuration.js";
+/** One model update policy for menu selections and command-line overrides. */
+export function selectModel(current, routes, offer, thinkingDefault, inputs, retainModels = false) {
+    const id = offer.model.id;
+    const selected = gatewayRoutesSchema.parse({
+        models: [
+            ...(routes?.models.filter((model) => model.id !== id && (retainModels || model.id !== routes.defaultModel)) ?? []),
+            { ...offer.model, enabled: true },
+        ],
+        defaultModel: id,
+        ...(thinkingDefault ? { thinkingDefault } : {}),
+    });
+    const sameCredentials = current?.mode === "litellm" &&
+        routes &&
+        selected.models.every((model) => routes.models.some((before) => before.route?.apiKeyEnv === model.route?.apiKeyEnv &&
+            before.route?.model.split("/")[0] ===
+                model.route?.model.split("/")[0]));
+    return {
+        mode: "litellm",
+        configurationFile: inputs.set("selected-models.json", JSON.stringify(selected, null, 2)),
+        upstreamEnvironmentFile: sameCredentials
+            ? current.upstreamEnvironmentFile
+            : "",
+    };
+}
+/** Recipes select an offering; model catalog metadata has one owner. */
+export function recipeModelRoutes(choice, catalog) {
+    const matches = catalog.filter((item) => item.model.enabled &&
+        item.model.id === choice.model &&
+        item.model.route.model.split("/")[0] === choice.provider);
+    const offer = matches[0];
+    if (!offer ||
+        matches.length !== 1 ||
+        (choice.reasoning && !offer.reasoningLevels.includes(choice.reasoning)))
+        throw new InstallationError("invalid_configuration", "Recipe model, provider and reasoning must select one enabled offering in the model catalog.");
+    return gatewayRoutesSchema.parse({
+        models: [offer.model],
+        defaultModel: choice.model,
+        ...(choice.reasoning ? { thinkingDefault: choice.reasoning } : {}),
+    });
+}