@clawscarf/cli 0.1.0-alpha.1

package/scripts/deployment/upgrade.js

@@ -0,0 +1,298 @@
+import { randomUUID } from "node:crypto";
+import { verifyRuntimeImage } from "./images.js";
+import { mkdtemp, writeFile, rm, chmod } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isDeepStrictEqual } from "node:util";
+import { setTimeout as delay } from "node:timers/promises";
+import { z } from "zod";
+import { parseLocalInput } from "./configuration.js";
+import { readState, resourceNames, withInstallationLock, writePrivate, } from "./state.js";
+import { readUpgrade, snapshotSchema } from "./upgrade-state.js";
+import { runtimeManager } from "./runtime.js";
+import { verifyRuntimeBinding } from "./runtime-binding.js";
+import { verifyLocalNetworks } from "./networks.js";
+import { verifyLocalExecutables } from "./preflight.js";
+import { LocalSetupError, run } from "./process.js";
+function refuse(detail) {
+    throw new LocalSetupError("upgrade_refused", detail);
+}
+function uncertain() {
+    throw new LocalSetupError("upgrade_outcome_unknown", "The upgrade has an unconfirmed external effect. Inspect its private state and controller before resuming; it will not repeat allocation or deletion.");
+}
+/** Requires exclusive operator control and the installation's own controller running. */
+export async function upgradeLocal(directoryInput, image, python, report, command = run) {
+    const directory = resolve(directoryInput);
+    await withInstallationLock(directory, async () => {
+        const state = await readState(directory);
+        await verifyRuntimeImage(image, command);
+        const next = {
+            ...state,
+            input: parseLocalInput({ ...state.input, runtimeImage: image }),
+        };
+        const names = resourceNames(state);
+        const controller = join(directory, "controller");
+        if (Object.keys(process.env).some((key) => key.startsWith("OPENSHELL_")))
+            refuse("Unset OPENSHELL_* overrides before upgrading this installation.");
+        const env = {
+            ...process.env,
+            XDG_CONFIG_HOME: join(controller, "config"),
+            XDG_STATE_HOME: join(controller, "state"),
+            XDG_DATA_HOME: join(controller, "data"),
+        };
+        await verifyLocalExecutables(state);
+        await verifyLocalNetworks(directory, state, command);
+        const running = await command("docker", [
+            "container",
+            "ls",
+            "--quiet",
+            "--filter",
+            `label=com.docker.compose.project=${names.project}`,
+            "--filter",
+            "label=com.docker.compose.service=companion",
+        ]);
+        if (running.trim())
+            refuse("Stop the installation and its access companion before upgrading. Start only its private controller.");
+        const gate = await command("docker", [
+            "image",
+            "inspect",
+            "--format",
+            '{{index .Config.Labels "io.clawscarf.start-gate"}}',
+            image,
+        ]);
+        if (gate.trim() !== "1")
+            refuse("The selected exact runtime image does not support the replacement startup gate.");
+        const control = runtimeManager(directory, state, env, command);
+        let upgrade = await readUpgrade(directory);
+        if (upgrade?.stage === "complete" &&
+            upgrade.toImage === image &&
+            state.input.runtimeImage === image) {
+            report("This runtime upgrade is already complete.");
+            return;
+        }
+        if (upgrade?.stage === "complete")
+            upgrade = undefined;
+        async function rpc(action, value = {}) {
+            const response = z
+                .discriminatedUnion("ok", [
+                z.strictObject({ ok: z.literal(true), value: z.unknown() }),
+                z.strictObject({ ok: z.literal(false), code: z.string() }),
+            ])
+                .parse(JSON.parse(await command(python, [fileURLToPath(new URL("./upgrade-rpc.py", import.meta.url))], {
+                env,
+                timeout: 150000,
+                input: JSON.stringify({
+                    action,
+                    controller,
+                    name: names.sandbox,
+                    ownerId: state.ownerId,
+                    ...value,
+                }),
+            })));
+            if (!response.ok) {
+                if (response.code === "global_overrides_unsupported")
+                    refuse("This controller has global overrides. The pinned API cannot preserve hidden sandbox settings; remove neither compute nor data until that configuration has a supported upgrade path.");
+                if (response.code === "policy_not_loaded")
+                    refuse("The current policy is not confirmed loaded. Reconcile it before upgrading.");
+                if (response.code === "runtime_command_unsupported")
+                    refuse("The runtime uses a custom startup command. Its upgrade needs an explicit supported startup gate.");
+                refuse("The controller did not verify the upgrade configuration. Inspect the private upgrade record and current native state before resuming.");
+            }
+            return response.value;
+        }
+        async function save(value) {
+            await writePrivate(join(directory, "upgrade.json"), JSON.stringify(value) + "\n");
+        }
+        if (!upgrade) {
+            if (image === state.input.runtimeImage)
+                refuse("Choose a different exact runtime image.");
+            const records = await control.recorded();
+            const target = await control.observe();
+            if (!target ||
+                target.id !== records.receipt?.id ||
+                target.phase !== "Stopped")
+                refuse("Upgrade requires this installation's recorded runtime to be Stopped.");
+            const binding = await verifyRuntimeBinding(state, target, command);
+            const snapshot = snapshotSchema.parse(await rpc("snapshot", { id: target.id }));
+            upgrade = {
+                ownerId: state.ownerId,
+                generation: randomUUID(),
+                fromImage: state.input.runtimeImage,
+                toImage: image,
+                oldId: target.id,
+                oldContainerId: binding.containerId,
+                snapshot,
+                stage: "prepared",
+            };
+            await save(upgrade);
+        }
+        const operation = upgrade;
+        if (operation.ownerId !== state.ownerId ||
+            operation.toImage !== image ||
+            ![operation.fromImage, operation.toImage].includes(state.input.runtimeImage))
+            refuse("Resume the recorded upgrade with its exact image and installation.");
+        const advance = async (stage) => {
+            operation.stage = stage;
+            await save(operation);
+        };
+        const request = () => ({
+            snapshot: operation.snapshot,
+            id: operation.newId,
+        });
+        async function retainedVolume() {
+            const volume = z
+                .object({
+                Name: z.literal(names.volume),
+                Labels: z.record(z.string(), z.string()),
+            })
+                .parse(JSON.parse(await command("docker", [
+                "volume",
+                "inspect",
+                "--format",
+                '{"Name":{{json .Name}},"Labels":{{json .Labels}}}',
+                names.volume,
+            ])));
+            if (volume.Labels["clawscarf.installation"] !== state.ownerId)
+                refuse("The retained home volume's ownership changed.");
+        }
+        async function oldAbsent() {
+            if (await control.observe())
+                uncertain();
+            const ids = await command("docker", [
+                "container",
+                "ls",
+                "--all",
+                "--quiet",
+                "--no-trunc",
+                "--filter",
+                `id=${operation.oldContainerId}`,
+            ]);
+            if (ids.trim())
+                uncertain();
+            await retainedVolume();
+        }
+        if (operation.stage === "prepared") {
+            const current = snapshotSchema.parse(await rpc("snapshot", { id: operation.oldId }));
+            if (!isDeepStrictEqual(current, operation.snapshot))
+                refuse("Runtime configuration changed after the upgrade snapshot. No deletion was sent.");
+            await verifyRuntimeBinding({
+                ...state,
+                input: { ...state.input, runtimeImage: operation.fromImage },
+            }, { id: operation.oldId, name: names.sandbox }, command);
+            await advance("delete_sent");
+            report("Removing stopped compute; retaining its home volume…");
+            // Native deletion has no atomic UUID precondition. Never resend this request.
+            try {
+                await control.shell(["sandbox", "delete", names.sandbox]);
+            }
+            catch {
+                /* Reconcile absence below. */
+            }
+        }
+        if (operation.stage === "delete_sent") {
+            await oldAbsent();
+            await advance("deleted");
+        }
+        if (operation.stage === "deleted") {
+            await oldAbsent();
+            await advance("create_sent");
+            report("Creating the replacement with application startup gated…");
+            try {
+                await rpc("create", {
+                    ...request(),
+                    image,
+                    generation: operation.generation,
+                });
+            }
+            catch {
+                /* Observe the unique generation; never replay create. */
+            }
+        }
+        if (operation.stage === "create_sent") {
+            const target = await control.observe();
+            if (!target ||
+                target.labels["clawscarf.upgrade"] !== operation.generation ||
+                target.id === operation.oldId)
+                uncertain();
+            operation.newId = target.id;
+            await advance("created");
+        }
+        const id = operation.newId ?? uncertain();
+        async function confirm() {
+            const target = await control.confirm(id);
+            if (target.labels["clawscarf.upgrade"] !== operation.generation)
+                refuse("The replacement generation changed.");
+            return target;
+        }
+        async function ready() {
+            const deadline = Date.now() + 90000;
+            while (Date.now() < deadline) {
+                const target = await confirm();
+                if (target.phase === "Ready")
+                    return;
+                if (["Error", "Stopped"].includes(target.phase))
+                    refuse("The replacement did not become ready. Inspect the controller before resuming.");
+                await delay(500);
+            }
+            refuse("The replacement is still starting. Resume this same upgrade after inspecting the controller.");
+        }
+        if (operation.stage === "created") {
+            await ready();
+            await verifyRuntimeBinding(next, { id, name: names.sandbox }, command);
+            await advance("restore_sent");
+            report("Restoring the current controller settings…");
+        }
+        if (operation.stage === "restore_sent") {
+            await rpc("restore", request());
+            await advance("restored");
+        }
+        if (operation.stage === "restored") {
+            // Next normal startup reads restored settings before launching the application.
+            const target = await confirm();
+            if (target.phase !== "Stopped")
+                await control.shell(["sandbox", "stop", names.sandbox]);
+            if ((await confirm()).phase !== "Stopped")
+                refuse("The replacement has not confirmed Stopped.");
+            await rpc("verify", request());
+            await advance("stopped");
+        }
+        if (operation.stage === "stopped") {
+            const binding = await verifyRuntimeBinding(next, { id, name: names.sandbox }, command);
+            if ((await confirm()).phase !== "Stopped")
+                refuse("Keep the replacement stopped until the upgrade commits.");
+            const staging = await mkdtemp(join(directory, "private", "upgrade-gate-"));
+            try {
+                const marker = join(staging, "ready");
+                await writeFile(marker, operation.generation + "\n", { mode: 0o644 });
+                await chmod(marker, 0o644);
+                // docker cp assigns root ownership at the container destination. No guest runs here.
+                await command("docker", [
+                    "cp",
+                    marker,
+                    `${binding.containerId}:/etc/clawscarf-start-ready`,
+                ]);
+            }
+            finally {
+                await rm(staging, { recursive: true, force: true });
+            }
+            await advance("released");
+        }
+        if (operation.stage === "released") {
+            const target = await confirm();
+            if (target.phase !== "Stopped")
+                refuse("The upgraded runtime has not confirmed Stopped.");
+            await verifyRuntimeBinding(next, { id, name: names.sandbox }, command);
+            await advance("committing");
+        }
+        if (operation.stage === "committing") {
+            await confirm();
+            await verifyRuntimeBinding(next, { id, name: names.sandbox }, command);
+            const intent = { ownerId: state.ownerId, name: names.sandbox, image };
+            await writePrivate(join(directory, "runtime-create.json"), JSON.stringify(intent) + "\n");
+            await writePrivate(join(directory, "runtime.json"), JSON.stringify({ ...intent, id }) + "\n");
+            await writePrivate(join(directory, "installation.json"), JSON.stringify(next, null, 2) + "\n");
+            await advance("complete");
+        }
+        report("Runtime replacement complete; data retained. Stop the private controller, then start the installation to verify native administrator access. This is not a backup or data rollback.");
+    });
+}

package/scripts/deployment/volumes.js

@@ -0,0 +1,24 @@
+import { OperatorError } from "../errors.js";
+import { run } from "./process.js";
+export async function ensureOwnedVolume(name, ownerId) {
+    const listed = (await run("docker", ["volume", "ls", "--format", "{{.Name}}"]))
+        .trim()
+        .split("\n");
+    if (!listed.includes(name))
+        await run("docker", [
+            "volume",
+            "create",
+            "--label",
+            `clawscarf.installation=${ownerId}`,
+            name,
+        ]);
+    const label = (await run("docker", [
+        "volume",
+        "inspect",
+        name,
+        "--format",
+        '{{index .Labels "clawscarf.installation"}}',
+    ])).trim();
+    if (label !== ownerId)
+        throw new OperatorError("A volume with this name belongs to a different installation.");
+}

package/scripts/errors.js

@@ -0,0 +1,9 @@
+/** Deliberate operator diagnostics only. Never wrap raw subprocess or provider messages. */
+export class OperatorError extends Error {
+    code;
+    constructor(message, code = "operation_failed") {
+        super(message);
+        this.code = code;
+        this.name = "OperatorError";
+    }
+}

package/scripts/installation/administrator.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { compose } from "../deployment/compose.js";
+/** Local operator command; no public endpoint can issue an ownership claim. */
+export async function administratorSetup(directory, issue = false, verify = false) {
+    const output = await compose(directory, [
+        "exec",
+        "-T",
+        "-e",
+        "CLAWSCARF_ACCESS_CONFIG=/run/clawscarf/access.json",
+        "companion",
+        "node",
+        "services/access/runtime/setup.js",
+        ...(issue ? ["--issue"] : []),
+        ...(verify ? ["--verify"] : []),
+    ], issue || verify ? 60_000 : 3000);
+    return z
+        .strictObject({
+        complete: z.boolean(),
+        expiresAt: z.string().nullable(),
+        url: z.url().optional(),
+    })
+        .parse(JSON.parse(output));
+}

package/scripts/installation/command.js

@@ -0,0 +1,176 @@
+import { connectionCommands } from "../connections.js";
+import { peopleCommand } from "../people.js";
+import { confirmDeletion, deleteInstallation } from "./delete.js";
+import { writeResult } from "../output.js";
+import { createDevelopmentRelease } from "../release/create.js";
+import { Command, Option } from "commander";
+import { z } from "zod";
+import { access } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { installationSchema } from "./configuration.js";
+import { readJson } from "./files.js";
+import { startInstallation, controlInstallation, installationLogs, } from "./lifecycle.js";
+import { doctorInstallation } from "./doctor.js";
+import { localLogNames } from "../deployment/logs.js";
+import { upgradeLocal } from "../deployment/upgrade.js";
+import { installationCatalog } from "./recipes/catalog.js";
+import { defaultInstallationDirectory } from "./location.js";
+import { progress } from "./installer/prompts.js";
+import { runConfiguration } from "./installer/run.js";
+import { installationOptions } from "./options.js";
+import { InstallationError } from "./errors.js";
+import { administratorSetup } from "./administrator.js";
+export function installationCommand() {
+    const program = new Command("clawscarf")
+        .description("Install and operate a protected OpenClaw team server.")
+        .option("--json", "Print machine-readable results; diagnostics go to stderr");
+    program.addCommand(peopleCommand(program));
+    const output = (value, human) => {
+        writeResult(program, value, human);
+    };
+    installationOptions(program.command("configure"))
+        .description("Create or change an installation; prompts unless --non-interactive")
+        .option("--directory <path>", "Installation directory", defaultInstallationDirectory)
+        .option("--recipe <name-or-file>", "New installation: bundled recipe name or recipe JSON file")
+        .option("--cloud-url <url>", "Development override: ClawScarf Cloud origin")
+        .option("--cloud-credential-file <file>", "Private cloud credential for unattended registration")
+        .option("--non-interactive", "Use explicit options without prompting")
+        .option("--yes", "Approve changes to an existing installation, including a restart")
+        .addOption(new Option("--reapply <capability>", "Explicitly restore selected managed settings on an existing installation").choices(["models", "connections"]))
+        .option("--start", "Start after configuration")
+        .option("--no-start", "Leave the installation stopped")
+        .action(async (options) => {
+        const result = await runConfiguration({
+            ...options,
+            ...program.opts(),
+        });
+        if (options.nonInteractive)
+            output(result);
+    });
+    program
+        .command("recipes")
+        .description("List bundled recipes, models and packs")
+        .action(async () => {
+        output(await installationCatalog());
+    });
+    program
+        .command("release-create")
+        .description("Bundle a development release from already-built component inputs")
+        .requiredOption("--input <file>")
+        .requiredOption("--output <directory>")
+        .action(async (options) => {
+        const release = await createDevelopmentRelease({
+            inputFile: options.input,
+            outputDirectory: options.output,
+        });
+        output({ version: release.version, directory: options.output });
+    });
+    withLocation(program.command("start")).action(async (options) => {
+        const state = await resolveLocation(options);
+        const result = await progress("Starting ClawScarf", (signal, report) => startInstallation(state, report, signal), program.opts());
+        output(result, statusText(result));
+    });
+    withLocation(program.command("administrator"))
+        .description("Observe or issue the private first-administrator setup link")
+        .option("--issue", "Replace the pending setup link; cannot reclaim an initialized server")
+        .action(async (options) => {
+        output(await administratorSetup(await resolveLocation(options), options.issue));
+    });
+    for (const action of ["status", "stop"]) {
+        const command = withLocation(program.command(action));
+        if (action === "stop")
+            command
+                .option("--delete", "Permanently delete this installation's Docker resources and data")
+                .option("--confirm-delete <directory>", "Unattended deletion: confirm the exact absolute installation directory")
+                .option("--accept-data-loss", "Unattended deletion: acknowledge permanent loss of all installation data");
+        command.action(async (options) => {
+            if (options.delete) {
+                await confirmDeletion(resolve(options.directory), {
+                    ...options,
+                    ...program.opts(),
+                });
+                const directory = await resolveLocation(options);
+                const result = await progress("Deleting installation", (signal) => deleteInstallation(directory, signal), program.opts());
+                output(result, "Installation deleted from Docker. You can now remove its installation folder.");
+                return;
+            }
+            if (options.confirmDelete !== undefined || options.acceptDataLoss)
+                throw new InstallationError("invalid_configuration", "Deletion confirmations require --delete.");
+            const result = await controlInstallation(await resolveLocation(options), action);
+            output(result, statusText(result));
+        });
+    }
+    withLocation(program.command("logs"))
+        .requiredOption("--service <name>", localLogNames.join(", "))
+        .action(async (options) => {
+        const { service } = options;
+        const text = await installationLogs(await resolveLocation(options), service);
+        if (program.opts().json)
+            output({ service, text });
+        else
+            process.stdout.write(text);
+    });
+    withLocation(program.command("doctor")).action(async ({ directory }) => {
+        const accepted = join(await resolveLocation({ directory }), "settings.json");
+        let config = accepted;
+        try {
+            await access(accepted);
+        }
+        catch (error) {
+            if (!(error instanceof Error &&
+                "code" in error &&
+                error.code === "ENOENT"))
+                throw error;
+            config = join(resolve(directory), "installation.json");
+        }
+        output(await doctorInstallation(config));
+    });
+    withLocation(program.command("upgrade"))
+        .requiredOption("--runtime-image <digest>")
+        .requiredOption("--python <executable>")
+        .requiredOption("--yes")
+        .action(async (options) => {
+        await upgradeLocal(await resolveLocation(options), options.runtimeImage, options.python, (message) => {
+            process.stderr.write(message + "\n");
+        });
+        output({ state: "upgraded" }, "Upgrade completed.");
+    });
+    const connections = program
+        .command("connections")
+        .description("Manage connected accounts and their agent access");
+    connectionCommands(connections, program);
+    return program;
+}
+function statusText(status) {
+    const lines = [
+        `Server: ${status.state}`,
+        `Ready: ${status.ready ? "Yes" : "No"}`,
+    ];
+    if ("administrator" in status) {
+        lines.push(`Administrator: ${status.administrator}`);
+        if (status.administrator === "pending")
+            lines.push("Complete administrator setup with clawscarf administrator --issue and your installation directory.");
+        for (const pack of status.packs)
+            lines.push(`Pack ${pack.member}: ${pack.state}`);
+    }
+    return lines.join("\n");
+}
+function withLocation(command) {
+    return command.option("--directory <path>", "Installation directory selected during configure", defaultInstallationDirectory);
+}
+/** Read only the location contract so stop/delete still work with invalid startup settings. */
+async function resolveLocation({ directory }) {
+    let value;
+    try {
+        value = await readJson(join(resolve(directory), "installation.json"));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            throw new InstallationError("unavailable", `No installation found in ${resolve(directory)}. Run clawscarf configure to create one, or use --directory to select an existing installation.`);
+        throw error;
+    }
+    const config = z
+        .object({ stateDirectory: installationSchema.shape.stateDirectory })
+        .parse(value);
+    return resolve(directory, config.stateDirectory);
+}

package/scripts/installation/configuration.js

@@ -0,0 +1,104 @@
+import { cloudUrlSchema, defaultCloudUrl } from "../cloud/url.js";
+import { z } from "zod";
+import { localInput } from "../deployment/configuration.js";
+const path = z.string().min(1);
+const resources = z.strictObject({
+    cpu: localInput.shape.cpu,
+    memory: localInput.shape.memory,
+});
+export const externalLiteLlmSchema = z.strictObject({
+    mode: z.literal("external"),
+    configurationFile: path,
+    credentialFile: path,
+    caFile: path.optional(),
+});
+export const bundledLiteLlmSchema = z.strictObject({
+    mode: z.literal("litellm"),
+    configurationFile: path,
+    upstreamEnvironmentFile: path,
+});
+/** Product contract: the whole team runtime is always protected by OpenShell. */
+export const installationSchema = z
+    .strictObject({
+    schemaVersion: z.literal(1),
+    name: localInput.shape.name,
+    recipe: z
+        .strictObject({
+        id: z.string().min(1),
+        version: z.string().min(1).optional(),
+        release: z.string().min(1),
+    })
+        .optional(),
+    releaseFile: path,
+    stateDirectory: path,
+    exposure: z.discriminatedUnion("mode", [
+        z.strictObject({
+            mode: z.literal("local"),
+            applicationPort: z.number().int().min(1024).max(65535),
+            widgetPort: z.number().int().min(1024).max(65535),
+        }),
+        z.strictObject({
+            mode: z.literal("https"),
+            applicationOrigin: z.url(),
+            widgetOrigin: z.url(),
+            certificateFile: path,
+            keyFile: path,
+        }),
+    ]),
+    access: z.discriminatedUnion("mode", [
+        z.strictObject({
+            mode: z.literal("hosted"),
+            cloudUrl: cloudUrlSchema.default(defaultCloudUrl),
+            registrationFile: path.default("./secrets/hosted-login.json"),
+            administratorSubject: z.string().min(1).optional(),
+            administratorEmail: z.email().optional(),
+            administratorName: localInput.shape.administratorName,
+        }),
+        z.strictObject({
+            mode: z.literal("oidc"),
+            administratorName: localInput.shape.administratorName,
+            issuer: z.url(),
+            clientId: z.string().min(1),
+            clientSecretFile: path,
+            administratorSubject: z.string().min(1).optional(),
+            administratorEmail: z.email().optional(),
+        }),
+    ]),
+    resources: z.strictObject({ runtime: resources }),
+    browser: z.strictObject({ enabled: z.boolean() }),
+    models: z.discriminatedUnion("mode", [
+        externalLiteLlmSchema,
+        bundledLiteLlmSchema,
+    ]),
+    connections: z.strictObject({
+        mode: z.enum(["disabled", "hosted"]),
+        cloudUrl: cloudUrlSchema.default(defaultCloudUrl),
+        registrationFile: path.default("./secrets/connections-registration.json"),
+    }),
+    packOperator: z
+        .strictObject({
+        pythonExecutable: path,
+        experimentalClaws: z.literal(true),
+    })
+        .optional(),
+    packs: z
+        .array(z.strictObject({
+        directory: path,
+        members: z.array(z.string().regex(/^[a-z][a-z0-9-]{0,63}$/)).min(1),
+        bindingsFile: path.optional(),
+    }))
+        .max(32),
+})
+    .superRefine((value, context) => {
+    if (Boolean(value.access.administratorSubject) !==
+        Boolean(value.access.administratorEmail))
+        context.addIssue({
+            code: "custom",
+            message: "Supply both administrator subject and email, or omit both to claim the server after login.",
+        });
+    if (value.packs.length > 0 && !value.packOperator)
+        context.addIssue({
+            code: "custom",
+            message: "Selected packs require a Python OpenShell SDK and explicit experimental Claws acknowledgement.",
+        });
+});