@clawscarf/cli 0.1.0-alpha.1

package/scripts/deployment/connection-policy.js

@@ -0,0 +1,80 @@
+import { isDeepStrictEqual } from "node:util";
+import { readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { run } from "./process.js";
+import { resourceNames, writePrivate } from "./state.js";
+import { runtimeManager } from "./runtime.js";
+const ruleSchema = z.object({
+    name: z.string(),
+    endpoints: z.array(z.object({ host: z.string(), port: z.number(), tls: z.string() })),
+    binaries: z.array(z.object({ path: z.string() })),
+});
+const policySchema = z.looseObject({
+    network_policies: z.record(z.string(), z.unknown()),
+});
+/** Apply only the explicitly selected broker rule; never regenerate an operator's other policies. */
+export async function applyConnectionPolicy(directory, state, env, verify = false) {
+    const pending = join(directory, "private/connection-policy-change.json");
+    let text;
+    try {
+        text = await readFile(pending, "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    const change = z
+        .strictObject({
+        ownerId: z.literal(state.ownerId),
+        rule: ruleSchema.nullable(),
+    })
+        .parse(JSON.parse(text));
+    const base = join(directory, "private/runtime-policy.json");
+    const update = (policy) => {
+        if (change.rule)
+            policy.network_policies.connections_broker = change.rule;
+        else
+            delete policy.network_policies.connections_broker;
+        return policy;
+    };
+    const matches = (rule) => {
+        if (change.rule === null)
+            return rule === undefined;
+        const parsed = ruleSchema.safeParse(rule);
+        return parsed.success && isDeepStrictEqual(parsed.data, change.rule);
+    };
+    const name = resourceNames(state).sandbox;
+    if (!(await runtimeManager(directory, state, env, run).recorded()).receipt) {
+        if (verify)
+            throw Error("The configured runtime has not been recorded.");
+        await writePrivate(base, JSON.stringify(update(policySchema.parse(JSON.parse(await readFile(base, "utf8"))))));
+        return;
+    }
+    const observed = z
+        .object({
+        sandbox: z.literal(name),
+        policy_source: z.literal("sandbox"),
+        policy: policySchema,
+    })
+        .parse(JSON.parse(await run(state.input.openshellCli, [
+        "policy",
+        "get",
+        name,
+        "--gateway",
+        name,
+        "--base",
+        "--output",
+        "json",
+    ], { env })));
+    if (matches(observed.policy.network_policies.connections_broker)) {
+        if (verify)
+            await rm(pending);
+        return;
+    }
+    if (verify)
+        throw Error("The Connections network permission was not confirmed. The installation remains unavailable.");
+    await writePrivate(base, JSON.stringify(update(observed.policy)));
+    await run(state.input.openshellCli, ["policy", "set", name, "--gateway", name, "--policy", base], { env });
+}

package/scripts/deployment/connection-settings.js

@@ -0,0 +1,60 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { companionConfiguration } from "./configuration.js";
+import { loadInitialConnections, prepareInitialConnections, readInitialConnectionToken, } from "./connections.js";
+import { configureConnectionsVolume } from "./connections-runtime.js";
+import { writePrivate } from "./state.js";
+import { initialRuntimePolicy } from "./policy.js";
+/** Explicit capability edit, with the installation stopped and its operator lock held. */
+export async function applyConnectionSettings(directory, state, previous, credentialFile) {
+    const loaded = await loadInitialConnections(state.input.connections);
+    const endpoint = await prepareInitialConnections(directory, loaded, {
+        state,
+        apply: true,
+    });
+    const serverId = z
+        .object({ serverId: z.uuid() })
+        .parse(JSON.parse(await readFile(join(directory, "identity.json"), "utf8"))).serverId;
+    const credential = endpoint
+        ? {
+            token: await readInitialConnectionToken(credentialFile ?? ""),
+            ...(endpoint.ca ? { ca: endpoint.ca } : {}),
+        }
+        : undefined;
+    const target = endpoint ?? previous;
+    if (target) {
+        const result = await configureConnectionsVolume(state, {
+            kind: endpoint ? "configure" : "disable",
+            ownerId: state.ownerId,
+            serverId,
+            brokerUrl: target.brokerUrl,
+            ...(endpoint ? { enable: true } : {}),
+            ...(credential ? { credential } : {}),
+        });
+        if (endpoint
+            ? result.state !== "configured" ||
+                !result.enabled ||
+                result.credentialMatches !== true
+            : result.state !== "not_installed" && result.enabled)
+            throw Error("Connections settings were not confirmed by OpenClaw.");
+    }
+    await writePrivate(join(directory, "private/companion.json"), JSON.stringify(companionConfiguration(state.input)));
+    // The only Compose mount changed here belongs to Connections. Preserve other services and their addresses.
+    const file = join(directory, "compose.json");
+    const config = z
+        .looseObject({
+        services: z.looseObject({
+            companion: z.looseObject({ volumes: z.array(z.string()) }),
+        }),
+    })
+        .parse(JSON.parse(await readFile(file, "utf8")));
+    const mount = `${join(directory, "private/connections")}:/run/clawscarf/connections:ro`;
+    config.services.companion.volumes = config.services.companion.volumes.filter((value) => value !== mount);
+    if (loaded?.managementKey)
+        config.services.companion.volumes.push(mount);
+    await writePrivate(file, JSON.stringify(config));
+    const rule = initialRuntimePolicy("network_policies: {}", undefined, endpoint)
+        .network_policies.connections_broker ?? null;
+    await writePrivate(join(directory, "private/connection-policy-change.json"), JSON.stringify({ ownerId: state.ownerId, rule }));
+}

package/scripts/deployment/connections-runtime.js

@@ -0,0 +1,31 @@
+import { connectionsConfigurationResultSchema } from "../../runtime/connections-configuration.js";
+import { resourceNames } from "./state.js";
+import { run } from "./process.js";
+/** Caller holds the installation lock and has verified the stopped, owned native volume. */
+export async function configureConnectionsVolume(state, request, command = run) {
+    const names = resourceNames(state);
+    return connectionsConfigurationResultSchema.parse(JSON.parse(await command("docker", [
+        "run",
+        "--rm",
+        "-i",
+        "--pull",
+        "never",
+        "--network",
+        "none",
+        "--read-only",
+        "--cap-drop",
+        "ALL",
+        "--security-opt",
+        "no-new-privileges:true",
+        "--user",
+        "1000:1000",
+        "--tmpfs",
+        "/tmp:rw,nosuid,nodev,size=64m",
+        "--mount",
+        `type=volume,source=${names.volume},target=/home/node,volume-nocopy${request.kind === "observe" ? ",readonly" : ""}`,
+        "--entrypoint",
+        "node",
+        state.input.runtimeImage,
+        "/app/clawscarf/configure-connections-main.js",
+    ], { input: JSON.stringify(request), timeout: 60_000 })));
+}

package/scripts/deployment/connections.js

@@ -0,0 +1,213 @@
+import { OperatorError } from "../errors.js";
+import { constants } from "node:fs";
+import { createHash, X509Certificate } from "node:crypto";
+import { lstat, mkdir, mkdtemp, open, readdir, rename, rm, } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { networkRequirementSchema } from "../packs/policy.js";
+import { connectionsBrokerUrlSchema, connectionsInputSchema, } from "./configuration.js";
+import { LocalSetupError } from "./process.js";
+import { ensurePrivateFile, readState } from "./state.js";
+const maximumCertificateBytes = 64 * 1024;
+const endpointSchema = z.strictObject({
+    brokerUrl: connectionsBrokerUrlSchema,
+    network: networkRequirementSchema,
+    ca: z.string().min(1).max(maximumCertificateBytes).optional(),
+});
+export async function readInitialConnectionToken(path) {
+    return z
+        .string()
+        .min(1)
+        .max(512)
+        .regex(/^[\x21-\x7e]+$/u)
+        .parse((await readRegular(path, true, 4096)).toString("utf8").trim());
+}
+const ownerSchema = z.strictObject({
+    ownerId: z.uuid(),
+    mode: z.literal("external"),
+    endpointSha256: z.string().regex(/^[a-f0-9]{64}$/u),
+});
+function endpoint(brokerUrl, ca) {
+    const url = new URL(connectionsBrokerUrlSchema.parse(brokerUrl));
+    if (ca !== undefined)
+        new X509Certificate(ca);
+    return endpointSchema.parse({
+        brokerUrl: url.href.replace(/\/$/, ""),
+        network: {
+            host: url.hostname,
+            port: Number(url.port || "443"),
+            protocol: "tcp",
+            binary: "/usr/local/bin/node",
+        },
+        ...(ca === undefined ? {} : { ca }),
+    });
+}
+function changed() {
+    throw new LocalSetupError("configuration_changed", "The retained Connections configuration differs from this installation's initial inputs. Setup will not replace endpoints, trust certificates or management credentials.");
+}
+async function readRegular(path, privateFile, maximumBytes) {
+    if (!(await lstat(path)).isFile())
+        throw new OperatorError("Configuration must be a regular file");
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const metadata = await file.stat();
+        if (!metadata.isFile() ||
+            metadata.size > maximumBytes ||
+            (privateFile &&
+                (metadata.uid !== process.getuid?.() ||
+                    metadata.nlink !== 1 ||
+                    (metadata.mode & 0o077) !== 0)))
+            throw new OperatorError("Invalid configuration file");
+        const bytes = await file.readFile();
+        if (bytes.length > maximumBytes)
+            throw new OperatorError("Configuration file exceeds its size limit");
+        return bytes;
+    }
+    finally {
+        await file.close();
+    }
+}
+async function tree(directory, privateFiles, prefix = "") {
+    const metadata = await lstat(directory);
+    if (!metadata.isDirectory() ||
+        (privateFiles &&
+            (metadata.uid !== process.getuid?.() || (metadata.mode & 0o077) !== 0)))
+        throw new OperatorError("Invalid configuration directory");
+    const files = new Map();
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        const relative = prefix + entry.name;
+        const path = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            for (const [name, bytes] of await tree(path, privateFiles, relative + "/"))
+                files.set(name, bytes);
+        }
+        else if (entry.isFile())
+            files.set(relative, await readRegular(path, privateFiles, 128 * 1024 * 1024));
+        else
+            throw new OperatorError("Catalog entries must be regular files or directories");
+    }
+    return files;
+}
+async function writeFiles(directory, files) {
+    for (const [name, bytes] of files) {
+        const path = join(directory, name);
+        await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+        await ensurePrivateFile(path, bytes);
+    }
+}
+/** Snapshot and verify optional input before installation resource allocation. No provider call is made. */
+export async function loadInitialConnections(input) {
+    if (!input)
+        return undefined;
+    try {
+        const checked = connectionsInputSchema.parse(input);
+        const ca = checked.caFile
+            ? new TextDecoder("utf8", { fatal: true }).decode(await readRegular(checked.caFile, false, maximumCertificateBytes))
+            : undefined;
+        return {
+            mode: "external",
+            endpoint: endpoint(checked.brokerUrl, ca),
+            ...(checked.managementKeyFile
+                ? {
+                    managementKey: await readInitialConnectionToken(checked.managementKeyFile),
+                }
+                : {}),
+        };
+    }
+    catch {
+        throw new LocalSetupError("invalid_connections_setup", "Connections requires an HTTPS DNS endpoint, a private management credential when supplied, and a valid trust certificate when supplied. Configuration files cannot be symbolic links.");
+    }
+}
+/** Caller holds the installation lock. A complete private snapshot is published once, never refreshed. */
+export async function prepareInitialConnections(directory, loaded, replacement) {
+    if (!loaded)
+        return;
+    const state = replacement?.state ?? (await readState(directory));
+    const input = state.input.connections;
+    if (input?.mode !== loaded.mode)
+        changed();
+    if (input.brokerUrl.replace(/\/$/, "") !== loaded.endpoint.brokerUrl)
+        changed();
+    const runtime = loaded.endpoint;
+    const endpointBytes = Buffer.from(JSON.stringify(runtime) + "\n");
+    const expected = new Map([
+        [
+            "owner.json",
+            Buffer.from(JSON.stringify({
+                ownerId: state.ownerId,
+                mode: loaded.mode,
+                endpointSha256: createHash("sha256")
+                    .update(endpointBytes)
+                    .digest("hex"),
+            }) + "\n"),
+        ],
+        ["endpoint.json", endpointBytes],
+    ]);
+    if (loaded.managementKey)
+        expected.set("management-key", Buffer.from(loaded.managementKey));
+    const target = join(directory, "private/connections");
+    try {
+        await lstat(target);
+        const retained = await tree(target, true);
+        if (retained.size !== expected.size ||
+            [...expected].some(([path, bytes]) => !retained.get(path)?.equals(bytes)))
+            changed();
+        return runtime;
+    }
+    catch (error) {
+        if (!(error instanceof Error &&
+            "code" in error &&
+            error.code === "ENOENT" &&
+            "path" in error &&
+            error.path === target))
+            changed();
+    }
+    if (replacement && !replacement.apply)
+        return runtime;
+    const staging = await mkdtemp(join(directory, "private/.connections-"));
+    try {
+        await writeFiles(staging, expected);
+        // Reserve the destination before rename so an existing foreign empty directory is never adopted.
+        await mkdir(target, { mode: 0o700 });
+        await rename(staging, target);
+        return runtime;
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+}
+/** Read only retained public endpoint/trust material; never reads a provider or runtime credential. */
+export async function readInitialConnectionsEndpoint(directory) {
+    const state = await readState(directory);
+    if (!state.input.connections)
+        return undefined;
+    try {
+        const target = join(directory, "private/connections");
+        for (const path of [join(directory, "private"), target]) {
+            const info = await lstat(path);
+            if (!info.isDirectory() ||
+                info.uid !== process.getuid?.() ||
+                (info.mode & 0o077) !== 0)
+                changed();
+        }
+        const owner = ownerSchema.parse(JSON.parse((await readRegular(join(target, "owner.json"), true, 8192)).toString("utf8")));
+        const endpointBytes = await readRegular(join(target, "endpoint.json"), true, 1024 * 1024);
+        if (createHash("sha256").update(endpointBytes).digest("hex") !==
+            owner.endpointSha256)
+            changed();
+        const retained = endpointSchema.parse(JSON.parse(endpointBytes.toString("utf8")));
+        const input = state.input.connections;
+        if (owner.ownerId !== state.ownerId)
+            changed();
+        const expected = endpoint(input.brokerUrl, retained.ca);
+        if (Boolean(input.caFile) !== (retained.ca !== undefined) ||
+            retained.brokerUrl !== expected.brokerUrl ||
+            retained.ca !== expected.ca ||
+            JSON.stringify(retained.network) !== JSON.stringify(expected.network))
+            changed();
+        return retained;
+    }
+    catch {
+        changed();
+    }
+}

package/scripts/deployment/controller-compose.js

@@ -0,0 +1,59 @@
+import { join } from "node:path";
+import { openshellGatewayImage } from "./images.js";
+import { resourceNames } from "./state.js";
+/** OpenShell alone receives Docker authority. Forwarders receive only client credentials. */
+export function controllerServices(directory, state) {
+    const controller = join(directory, "controller");
+    const { input } = state;
+    const name = resourceNames(state).sandbox;
+    const port = input.ports.controller;
+    const forward = (target, port) => ({
+        image: input.openshellClientImage,
+        init: true,
+        read_only: true,
+        cap_drop: ["ALL"],
+        security_opt: ["no-new-privileges:true"],
+        tmpfs: ["/tmp"],
+        environment: {
+            HOME: "/tmp",
+            XDG_CONFIG_HOME: "/controller/config",
+            XDG_STATE_HOME: "/tmp/state",
+            XDG_DATA_HOME: "/tmp/data",
+        },
+        volumes: [`${join(controller, "config")}:/controller/config:ro`],
+        extra_hosts: ["host.openshell.internal:host-gateway"],
+        command: [
+            "forward",
+            "start",
+            `0.0.0.0:${String(port)}`,
+            target,
+            "--gateway",
+            name,
+            "--gateway-endpoint",
+            `https://host.openshell.internal:${String(input.ports.controller)}`,
+        ],
+        ports: [`127.0.0.1:${String(port)}:${String(port)}`],
+    });
+    return {
+        controller: {
+            image: openshellGatewayImage,
+            user: "0:0",
+            command: ["--config", join(controller, "gateway.toml")],
+            environment: {
+                XDG_CONFIG_HOME: join(controller, "config"),
+                XDG_STATE_HOME: join(controller, "state"),
+                XDG_DATA_HOME: join(controller, "data"),
+                HOME: controller,
+            },
+            // Identical paths are required: Docker resolves sandbox mounts on its host.
+            volumes: [
+                `${controller}:${controller}`,
+                "/var/run/docker.sock:/var/run/docker.sock",
+            ],
+            ports: [`127.0.0.1:${String(port)}:${String(port)}`],
+            extra_hosts: ["host.openshell.internal:host-gateway"],
+        },
+        application: forward(name, input.ports.native),
+        widgets: forward(name, input.ports.nativeWidgets),
+    };
+}

package/scripts/deployment/database.js

@@ -0,0 +1,199 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { compose } from "./compose.js";
+import { LocalSetupError } from "./process.js";
+import pg from "pg";
+import { runner } from "node-pg-migrate";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+const inputSchema = z.strictObject({
+    adminUrl: z.string(),
+    runtimePassword: z
+        .string()
+        .min(24)
+        .max(1024)
+        .refine((v) => !v.includes("\0")),
+    ownerId: z.uuid(),
+});
+export class LocalDatabaseError extends Error {
+    code;
+    constructor(code) {
+        super({
+            invalid_configuration: "Use the isolated local clawscarf database and private setup credentials.",
+            ownership_conflict: "This database or runtime role is not owned by this local installation.",
+            runtime_credentials_changed: "The saved runtime credentials do not match this local installation.",
+            database_setup_failed: "Local database setup failed. Check the local PostgreSQL service and setup configuration.",
+        }[code]);
+        this.code = code;
+    }
+}
+const quiet = () => undefined;
+/** Operator-only initialization. Never call from companion startup. */
+export async function initializeLocalDatabase(input) {
+    const parsed = inputSchema.safeParse(input);
+    if (!parsed.success)
+        throw new LocalDatabaseError("invalid_configuration");
+    let url;
+    try {
+        url = new URL(input.adminUrl);
+        decodeURIComponent(url.username);
+        decodeURIComponent(url.password);
+    }
+    catch {
+        throw new LocalDatabaseError("invalid_configuration");
+    }
+    if (!["postgres:", "postgresql:"].includes(url.protocol) ||
+        !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname) ||
+        url.pathname !== "/clawscarf" ||
+        !url.username ||
+        !url.password ||
+        url.search ||
+        url.hash ||
+        decodeURIComponent(url.username) === "clawscarf_runtime")
+        throw new LocalDatabaseError("invalid_configuration");
+    const runtimeUrl = new URL(url);
+    runtimeUrl.username = "clawscarf_runtime";
+    runtimeUrl.password = encodeURIComponent(input.runtimePassword);
+    const client = new pg.Client({ connectionString: url.toString() });
+    let connected = false;
+    try {
+        await client.connect();
+        connected = true;
+        await client.query("SELECT pg_advisory_lock(17893240, 1)");
+        const facts = await client.query(`SELECT
+      (SELECT datdba = (SELECT oid FROM pg_roles WHERE rolname = current_user) FROM pg_database WHERE datname = current_database()) AS owned,
+      to_regnamespace('clawscarf_operator')::text AS marker,
+      EXISTS(SELECT FROM pg_roles WHERE rolname = 'clawscarf_runtime') AS role_exists`);
+        const fact = facts.rows[0];
+        if (!fact?.owned)
+            throw new LocalDatabaseError("ownership_conflict");
+        if (!fact.marker) {
+            const objects = await client.query(`SELECT
+        EXISTS(SELECT FROM pg_namespace WHERE nspname NOT IN ('public', 'information_schema') AND nspname !~ '^pg_')
+        OR EXISTS(SELECT FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE n.nspname = 'public')
+        OR EXISTS(SELECT FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace WHERE n.nspname = 'public')
+        OR EXISTS(SELECT FROM pg_type t JOIN pg_namespace n ON n.oid = t.typnamespace WHERE n.nspname = 'public')
+        OR EXISTS(SELECT FROM pg_extension WHERE extname != 'plpgsql') AS dirty`);
+            if (fact.role_exists || objects.rows[0]?.dirty !== false)
+                throw new LocalDatabaseError("ownership_conflict");
+            await client.query("BEGIN");
+            try {
+                await client.query("CREATE SCHEMA clawscarf_operator");
+                await client.query("REVOKE ALL ON SCHEMA clawscarf_operator FROM PUBLIC");
+                await client.query("CREATE TABLE clawscarf_operator.installation (singleton boolean PRIMARY KEY CHECK(singleton), owner_id uuid NOT NULL)");
+                await client.query("INSERT INTO clawscarf_operator.installation VALUES (true, $1)", [input.ownerId]);
+                const statement = await client.query("SELECT format('CREATE ROLE clawscarf_runtime LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOINHERIT NOREPLICATION NOBYPASSRLS PASSWORD %L', $1::text) AS sql", [input.runtimePassword]);
+                const sql = statement.rows[0]?.sql;
+                if (!sql)
+                    throw new LocalDatabaseError("database_setup_failed");
+                await client.query(sql);
+                await client.query("COMMIT");
+            }
+            catch (error) {
+                await client.query("ROLLBACK");
+                throw error;
+            }
+        }
+        else {
+            const marker = await client.query(`SELECT owner_id,
+        (SELECT nspowner = (SELECT oid FROM pg_roles WHERE rolname = current_user) FROM pg_namespace WHERE nspname = 'clawscarf_operator')
+        AND (SELECT relowner = (SELECT oid FROM pg_roles WHERE rolname = current_user) FROM pg_class WHERE oid = 'clawscarf_operator.installation'::regclass) AS operator_owned
+        FROM clawscarf_operator.installation WHERE singleton`);
+            if (marker.rowCount !== 1 ||
+                marker.rows[0]?.owner_id !== input.ownerId ||
+                !marker.rows[0].operator_owned ||
+                !fact.role_exists)
+                throw new LocalDatabaseError("ownership_conflict");
+            const runtime = new pg.Client({
+                connectionString: runtimeUrl.toString(),
+            });
+            try {
+                await runtime.connect();
+                await runtime.query("SELECT 1");
+            }
+            catch {
+                throw new LocalDatabaseError("runtime_credentials_changed");
+            }
+            finally {
+                await runtime.end();
+            }
+        }
+        const authority = await client.query(`SELECT NOT (rolsuper OR rolcreatedb OR rolcreaterole OR rolinherit OR rolreplication OR rolbypassrls)
+      AND NOT EXISTS(SELECT FROM pg_auth_members WHERE member = r.oid)
+      AND NOT EXISTS(SELECT FROM pg_database WHERE datdba = r.oid)
+      AND NOT EXISTS(SELECT FROM pg_namespace WHERE nspowner = r.oid)
+      AND NOT EXISTS(SELECT FROM pg_class WHERE relowner = r.oid) AS safe
+      FROM pg_roles r WHERE rolname = 'clawscarf_runtime'`);
+        if (!authority.rows[0]?.safe)
+            throw new LocalDatabaseError("ownership_conflict");
+        await runner({
+            dbClient: client,
+            dir: fileURLToPath(new URL("../../services/access/migrations", import.meta.url)),
+            direction: "up",
+            migrationsTable: "clawscarf_access_migrations",
+            count: Infinity,
+            logger: { debug: quiet, info: quiet, warn: quiet, error: quiet },
+        });
+        await client.query("BEGIN");
+        try {
+            await client.query("REVOKE ALL ON DATABASE clawscarf FROM PUBLIC, clawscarf_runtime");
+            await client.query("GRANT CONNECT ON DATABASE clawscarf TO clawscarf_runtime");
+            await client.query("REVOKE ALL ON SCHEMA public FROM PUBLIC, clawscarf_runtime");
+            await client.query("REVOKE ALL ON SCHEMA clawscarf_operator FROM PUBLIC, clawscarf_runtime");
+            await client.query("REVOKE ALL ON SCHEMA clawscarf_access FROM PUBLIC, clawscarf_runtime");
+            await client.query("GRANT USAGE ON SCHEMA clawscarf_access TO clawscarf_runtime");
+            await client.query("REVOKE ALL ON ALL TABLES IN SCHEMA clawscarf_access FROM PUBLIC, clawscarf_runtime");
+            await client.query("GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA clawscarf_access TO clawscarf_runtime");
+            await client.query("COMMIT");
+        }
+        catch (error) {
+            await client.query("ROLLBACK");
+            throw error;
+        }
+        return { runtimeUrl: runtimeUrl.toString() };
+    }
+    catch (error) {
+        if (error instanceof LocalDatabaseError)
+            throw error;
+        throw new LocalDatabaseError("database_setup_failed");
+    }
+    finally {
+        if (connected)
+            await client.end();
+    }
+}
+/** Operator-only database preparation; always close its temporary service and pool. */
+export async function withPreparedDatabase(directory, state, operation) {
+    try {
+        try {
+            await compose(directory, [
+                "up",
+                "-d",
+                "--wait",
+                "--wait-timeout",
+                "90",
+                "postgres",
+            ]);
+        }
+        catch {
+            throw new LocalSetupError("database_start_failed", "PostgreSQL startup did not confirm success. Check this installation’s Compose logs and Docker network capacity.");
+        }
+        const adminUrl = new URL(`postgresql://postgres@127.0.0.1:${String(state.input.ports.database)}/clawscarf`);
+        adminUrl.password = await readFile(join(directory, "private/database-admin-password"), "utf8");
+        const { runtimeUrl } = await initializeLocalDatabase({
+            adminUrl: adminUrl.toString(),
+            runtimePassword: await readFile(join(directory, "private/database-runtime-password"), "utf8"),
+            ownerId: state.ownerId,
+        });
+        const pool = new pg.Pool({ connectionString: runtimeUrl });
+        try {
+            return await operation(pool, runtimeUrl);
+        }
+        finally {
+            await pool.end();
+        }
+    }
+    finally {
+        await compose(directory, ["stop", "postgres"]);
+    }
+}

package/scripts/deployment/entrypoint.js

@@ -0,0 +1,7 @@
+import { fileURLToPath } from "node:url";
+/** Execute the same entry point from a contributor checkout or its compiled artifact. */
+export function nodeEntrypoint(relative) {
+    const source = import.meta.url.endsWith(".ts");
+    const file = new URL(relative + (source ? ".ts" : ".js"), import.meta.url);
+    return [...(source ? ["--import", "tsx"] : []), fileURLToPath(file)];
+}

package/scripts/deployment/images.js

@@ -0,0 +1,17 @@
+import components from "../../release/components.json" with { type: "json" };
+import { LocalSetupError, run } from "./process.js";
+/** Verify the runtime declares the packaged execution contract. */
+export async function verifyRuntimeImage(image, command = run) {
+    const model = await command("docker", [
+        "image",
+        "inspect",
+        "--format",
+        '{{index .Config.Labels "io.clawscarf.execution-model"}}',
+        image,
+    ]);
+    if (model.trim() !== "team-runtime")
+        throw new LocalSetupError("configuration_changed", "Use a runtime image built for the team-runtime execution model. The selected image has not declared that contract.");
+}
+export const liteLlmImage = "ghcr.io/berriai/litellm:v1.100.1@sha256:a3715fa7ad8387941ab697259bd2881d68931657247a41984f90fae6d11c62bf";
+export const postgresImage = "postgres@sha256:742f40ea20b9ff2ff31db5458d127452988a2164df9e17441e191f3b72252193";
+export const openshellGatewayImage = components.openshell.gatewayImage;