uc-config 0.1.0

package/dist/engine.d.ts

@@ -0,0 +1,32 @@
+import { Adapter } from "./adapter.js";
+import type { ObjectValue, Plan, SetupCheckpoint, State } from "./model.js";
+export interface Journal {
+    planDigest: string;
+    status: "running" | "paused" | "failed" | "complete";
+    entries: Array<{
+        key: string;
+        status: "intent" | "created" | "verified" | "awaiting-user";
+        id?: string;
+        before: ObjectValue | null;
+    }>;
+}
+export declare class PendingSetup extends Error {
+}
+export interface Store {
+    save(state: State): Promise<void>;
+    journal(journal: Journal): Promise<void>;
+}
+export declare class Engine {
+    readonly adapter: Adapter;
+    readonly store: Store;
+    constructor(adapter: Adapter, store: Store);
+    apply(plan: Plan, state: State): Promise<{
+        state: State;
+        journal: Journal;
+    }>;
+    private precondition;
+    private create;
+    private update;
+    finishSetup(setup: SetupCheckpoint, state: State): Promise<string>;
+    resume(state: State): Promise<string[]>;
+}

package/dist/engine.js

@@ -0,0 +1,276 @@
+import { route } from "./adapter.js";
+import { resolveSecrets } from "./client.js";
+import { configurationView, checkPlan } from "./planner.js";
+import { equal, hash, isObject, merge, project, resolveRefs } from "./util.js";
+import { validateRequest } from "./schema.js";
+export class PendingSetup extends Error {
+}
+export class Engine {
+    adapter;
+    store;
+    constructor(adapter, store) {
+        this.adapter = adapter;
+        this.store = store;
+    }
+    async apply(plan, state) {
+        checkPlan(plan);
+        await this.adapter.client.verifyTarget(plan.target);
+        if (state.identity !== plan.target.identity ||
+            state.revision !== plan.stateRevision)
+            throw new Error("State changed since plan; replan");
+        // Validate every precondition before issuing any writes. Only proven adoption
+        // IDs can be used for dependent preflight reads; newly created IDs are deferred.
+        const observedState = structuredClone(state);
+        for (const op of plan.operations) {
+            await this.precondition(op, observedState);
+            if (op.action === "adopt" && op.id)
+                observedState.bindings[op.key] = {
+                    id: op.id,
+                    resource: op.resource,
+                    baseline: op.desired,
+                };
+        }
+        const journal = {
+            planDigest: plan.digest,
+            status: "running",
+            entries: [],
+        };
+        await this.store.journal(journal);
+        try {
+            for (const op of plan.operations) {
+                await this.precondition(op, state);
+                const r = resolveRefs(op.resource, state);
+                let id = op.id;
+                const entry = {
+                    key: op.key,
+                    status: "intent",
+                    ...(id ? { id } : {}),
+                    before: op.before,
+                };
+                journal.entries.push(entry);
+                await this.store.journal(journal);
+                if (op.action === "delete") {
+                    await this.adapter.assertDeletable(r, id);
+                    const rt = route(r, id);
+                    const path = r.kind.endsWith("Button")
+                        ? `${rt.item}/${encodeURIComponent((r.id ?? "").split("/")[1])}`
+                        : rt.item;
+                    await this.adapter.client.request("DELETE", path);
+                    if (await this.adapter.client.maybe(path))
+                        throw new Error(`${op.key}: deletion not verified`);
+                    delete state.bindings[op.key];
+                    state.revision++;
+                    await this.store.save(state);
+                    entry.status = "verified";
+                    await this.store.journal(journal);
+                    continue;
+                }
+                if (op.action === "create" ||
+                    op.action === "reconfigure" ||
+                    (op.action === "update" &&
+                        ["asset", "driverArchive"].includes(r.kind))) {
+                    id =
+                        op.action === "update"
+                            ? await this.adapter.upload(r, true)
+                            : await this.create(op, r, state, journal);
+                    entry.id = id;
+                    entry.status = "created";
+                    await this.store.journal(journal);
+                    // ID is durable before configuration writes; on failure baseline remains empty.
+                    state.bindings[op.key] = { id, resource: op.resource, baseline: {} };
+                    state.revision++;
+                    await this.store.save(state);
+                }
+                if (!id)
+                    throw new Error(`${op.key}: missing identity`);
+                if (op.action !== "adopt" &&
+                    !["asset", "driverArchive"].includes(r.kind))
+                    await this.update(r, id, op.desired);
+                const obs = await this.adapter.observe({ ...op.resource, id }, state, op.key);
+                const actual = obs.value && configurationView(obs.value, op.desired, op.desired);
+                if (!equal(actual, op.desired))
+                    throw new Error(`${op.key}: read-back differs from desired configuration`);
+                state.bindings[op.key] = {
+                    id,
+                    resource: op.resource,
+                    baseline: op.desired,
+                };
+                state.revision++;
+                await this.store.save(state);
+                entry.status = "verified";
+                await this.store.journal(journal);
+            }
+            journal.status = "complete";
+            await this.store.journal(journal);
+            return { state, journal };
+        }
+        catch (e) {
+            journal.status = e instanceof PendingSetup ? "paused" : "failed";
+            await this.store.journal(journal);
+            throw e;
+        }
+    }
+    async precondition(op, state) {
+        const obs = await this.adapter.observe(op.resource, state, op.key);
+        const current = obs.value &&
+            configurationView(obs.value, merge(state.bindings[op.key]?.baseline ?? {}, op.desired), state.bindings[op.key]?.baseline);
+        if (!equal(current, op.before))
+            throw new Error(`${op.key}: remote changed since plan; replan`);
+    }
+    async create(op, r, state, journal) {
+        this.adapter.validate(r, true);
+        if (r.kind === "asset" || r.kind === "driverArchive")
+            return this.adapter.upload(r);
+        if (r.kind === "integration" || r.kind === "dock") {
+            const path = r.kind === "integration" ? "/intg/setup" : "/docks/setup";
+            const before = await this.adapter.client.list(r.kind === "integration" ? "/intg/instances" : "/docks");
+            const ids = before.map((x) => String(x[r.kind === "integration" ? "integration_id" : "dock_id"]));
+            if (r.kind === "integration") {
+                state.setups[op.key] = {
+                    key: op.key,
+                    kind: "integration",
+                    id: String(r.create?.driver_id),
+                    resource: op.resource,
+                    beforeIds: ids,
+                    ...(op.action === "reconfigure" ? { existingId: op.id } : {}),
+                    status: "STARTING",
+                };
+                state.revision++;
+                await this.store.save(state);
+            }
+            const setupBody = await resolveSecrets(op.action === "reconfigure"
+                ? { ...r.create, reconfigure: true }
+                : r.create);
+            validateRequest(path, "POST", setupBody);
+            const { data } = await this.adapter.client.request("POST", path, setupBody);
+            if (typeof data.id !== "string")
+                throw new Error("Setup returned no id");
+            const setup = {
+                key: op.key,
+                kind: r.kind,
+                id: data.id,
+                resource: op.resource,
+                beforeIds: ids,
+                ...(op.action === "reconfigure" ? { existingId: op.id } : {}),
+                status: String(data.state),
+            };
+            state.setups[op.key] = setup;
+            state.revision++;
+            await this.store.save(state);
+            journal.entries.at(-1).id = data.id;
+            journal.entries.at(-1).status = "awaiting-user";
+            await this.store.journal(journal);
+            return this.finishSetup(setup, state);
+        }
+        if (r.kind === "entity") {
+            const path = `/intg/instances/${encodeURIComponent(String(r.parent))}/entities/${encodeURIComponent(String(r.create?.entity_id))}`;
+            const { data } = await this.adapter.client.request("POST", path, await resolveSecrets(r.data));
+            if (typeof data.entity_id !== "string")
+                throw new Error("Entity provisioning returned no entity_id");
+            return data.entity_id;
+        }
+        const rt = route(r, op.id);
+        const path = r.kind === "irCode" ? rt.item : rt.collection;
+        const createBody = await resolveSecrets(r.create ?? r.data);
+        validateRequest(r.kind === "irCode" ? rt.itemTemplate : rt.collectionTemplate, "POST", createBody);
+        const { data } = await this.adapter.client.request("POST", path, createBody);
+        const id = data[rt.idField] ?? op.id ?? r.id;
+        if (typeof id !== "string")
+            throw new Error(`${op.key}: create returned no ${rt.idField}`);
+        return id;
+    }
+    async update(r, id, data) {
+        const rt = route(r, id);
+        if (r.kind === "pairing") {
+            const live = await this.adapter.client.get(rt.item);
+            if (live.paired === true) {
+                if (!equal(project(live, data), data))
+                    throw new Error("Bluetooth peer differs; explicit unpairing/replacement required");
+                return;
+            }
+            if (live.pairing_enabled !== true)
+                await this.adapter.client.request("PUT", `${rt.item}?enabled=true`);
+            throw new PendingSetup(`Bluetooth pairing enabled for ${String(r.parent)}. Pair on the device; use pairing respond for any passkey, then replan.`);
+        }
+        if (!Object.keys(data).length)
+            return;
+        let body = data;
+        const current = await this.adapter.client.get(rt.item);
+        body = Object.fromEntries(Object.entries(data).map(([k, v]) => [
+            k,
+            isObject(v) && !("$secret" in v) && isObject(current[k])
+                ? merge(current[k], v)
+                : v,
+        ]));
+        if (["activity", "macro"].includes(r.kind) && isObject(body.options)) {
+            for (const k of [
+                "included_entities",
+                "editable",
+                "activity_group",
+                "button_mapping",
+                "user_interface",
+            ])
+                delete body.options[k];
+        }
+        if (r.kind === "integration") {
+            body = Object.fromEntries(Object.entries(body).filter(([k]) => !["driver_id", "device_id"].includes(k)));
+        }
+        if (r.kind === "driver") {
+            body = Object.fromEntries(Object.entries(body).filter(([k]) => k !== "driver_id"));
+        }
+        if (Object.keys(body).length) {
+            validateRequest(rt.itemTemplate, "PATCH", body);
+            const resolvedBody = await resolveSecrets(body);
+            validateRequest(rt.itemTemplate, "PATCH", resolvedBody);
+            await this.adapter.client.request("PATCH", rt.item, resolvedBody);
+        }
+    }
+    async finishSetup(setup, state) {
+        const r = resolveRefs(setup.resource, state);
+        const base = setup.kind === "integration" ? "/intg/setup" : "/docks/setup";
+        const status = await this.adapter.client.get(`${base}/${encodeURIComponent(setup.id)}`);
+        setup.status = String(status.state);
+        await this.store.save(state);
+        if (status.state === "ERROR")
+            throw new Error(`${setup.key}: setup failed (${String(status.error)}); inspect setup status before restarting`);
+        if (status.state !== "OK")
+            throw new PendingSetup(`${setup.key}: ${status.state}; run setup status/resume${status.state === "WAIT_USER_ACTION" ? " and provide the requested input" : ""}`);
+        const list = await this.adapter.client.list(setup.kind === "integration" ? "/intg/instances" : "/docks");
+        const field = setup.kind === "integration" ? "integration_id" : "dock_id";
+        const matches = list.filter((x) => (setup.existingId
+            ? x[field] === setup.existingId
+            : !setup.beforeIds.includes(String(x[field]))) &&
+            (setup.kind === "dock"
+                ? x.dock_id === setup.id
+                : x.driver_id === r.create?.driver_id &&
+                    (!r.data.device_id || x.device_id === r.data.device_id)));
+        if (matches.length !== 1)
+            throw new Error(`${setup.key}: setup finished but resulting identity is ambiguous; inspect inventory and adopt explicitly`);
+        const id = String(matches[0][field]);
+        state.bindings[setup.key] = {
+            id,
+            resource: setup.resource,
+            baseline: {},
+            setupHash: hash(setup.resource.create),
+        };
+        delete state.setups[setup.key];
+        state.revision++;
+        await this.store.save(state);
+        return id;
+    }
+    async resume(state) {
+        const messages = [];
+        for (const s of Object.values(state.setups))
+            try {
+                const id = await this.finishSetup(s, state);
+                messages.push(`${s.key}: provisioned ${id}; replan configuration`);
+            }
+            catch (e) {
+                if (e instanceof PendingSetup)
+                    messages.push(e.message);
+                else
+                    throw e;
+            }
+        return messages;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./dsl.js";
+export type { Config, Resource, Ref, Secret, Id, Json, ObjectValue, } from "./model.js";

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./dsl.js";

package/dist/init.d.ts

@@ -0,0 +1,7 @@
+export interface InitResult {
+    written: string[];
+    skipped: string[];
+    packageJsonUpdated: boolean;
+}
+/** Scaffold a private config workspace. Never overwrites existing files. */
+export declare function init(dir: string, version: string): Promise<InitResult>;

package/dist/init.js

@@ -0,0 +1,124 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+const agents = (version) => `# Remote 3 configuration (uc-config)
+
+This folder holds the user's Unfolded Circle Remote 3 configuration. It is
+managed with the \`uc-config\` CLI (v${version}). Reference docs ship with the package:
+
+- node_modules/uc-config/README.md: setup, diagnostics, Integration Manager
+- node_modules/uc-config/docs/snippets.md: recipes for common tasks (start here)
+- node_modules/uc-config/docs/cli.md: every command, recovery
+- node_modules/uc-config/docs/configuration-authoring.md: config syntax and ownership
+
+## First run (no .uc/targets/ yet)
+
+1. \`npx uc-config connect home --host http://<IP>\`. Ask the user for the IP if not given.
+2. Ask the user to run \`npx uc-config auth\` in their own terminal (the web
+   configurator must be enabled on the remote). Never ask for the PIN in chat.
+3. \`npx uc-config doctor\`
+4. \`npx uc-config inventory --bindings generated/devices.ts\`
+5. \`npx uc-config import --out remote.config.ts\`
+6. \`npx uc-config compile && npx uc-config plan --out .uc/plan.json\`. Expect only \`= adopt\` operations.
+7. \`npx uc-config apply .uc/plan.json --adopt-only && npx uc-config check\`
+8. \`git init && git add -A && git commit -m "Import Remote 3 config"\`
+
+If \`.uc/\` already exists, reuse it. Don't re-auth, re-import or re-adopt.
+
+## Every change
+
+Edit remote.config.ts, then: \`npx tsc --noEmit\`, \`npx uc-config compile\`,
+\`npx uc-config plan --out .uc/plan.json\`, review, \`npx uc-config apply .uc/plan.json\`,
+\`npx uc-config check\` (must be 0 operations).
+
+- Use only entity IDs and cmd_ids from generated/devices.ts or a fresh inventory.
+  Never invent command names.
+- A command must belong to an entity in the activity's/macro's \`entity_ids\`.
+- Arrays (entity_ids, sequences, page items) are replaced whole: keep existing
+  entries and order.
+- Preserve resource keys and native \`id\`s. Never hand-edit files in .uc/.
+- The plan must contain only the intended change. Anything else: stop and ask.
+- Never use --overwrite-drift or --prune without the user's say-so.
+- Never put secrets in remote.config.ts or print .uc/credentials.json.
+
+## When something is broken
+
+Run \`npx uc-config diagnose\`. It is read-only and prints a \`fix:\` per issue.
+Re-adding a dropped entity the integration still offers is safe to do
+directly. Ask before anything else. Integration installs and updates belong to
+the UC Integration Manager (http://<remote>:9999); run diagnose after any update.
+
+## Upgrading the tool
+
+\`npm update uc-config\`, then compile and plan. The plan must show 0 operations
+before you make any other change.
+`;
+const tsconfig = {
+    compilerOptions: {
+        target: "ES2023",
+        module: "NodeNext",
+        moduleResolution: "NodeNext",
+        strict: true,
+        noEmit: true,
+        skipLibCheck: true,
+    },
+    include: ["remote.config.ts", "generated/**/*.ts"],
+};
+const gitignore = `node_modules/
+# Credentials, state and journals. Back up .uc/state and .uc/journals privately.
+.uc/
+.env
+.env.*
+`;
+/** Scaffold a private config workspace. Never overwrites existing files. */
+export async function init(dir, version) {
+    await mkdir(dir, { recursive: true });
+    const result = {
+        written: [],
+        skipped: [],
+        packageJsonUpdated: false,
+    };
+    const put = async (name, contents) => {
+        try {
+            await writeFile(join(dir, name), contents, { flag: "wx" });
+            result.written.push(name);
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+            result.skipped.push(name);
+        }
+    };
+    const pkgPath = join(dir, "package.json");
+    let pkg;
+    try {
+        pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    if (!pkg) {
+        await put("package.json", JSON.stringify({
+            name: "my-remote",
+            private: true,
+            type: "module",
+            dependencies: { "uc-config": `^${version}` },
+            devDependencies: { typescript: "^5.9.3" },
+        }, null, 2) + "\n");
+    }
+    else if (!pkg.dependencies?.["uc-config"] &&
+        !pkg.devDependencies?.["uc-config"]) {
+        pkg.dependencies = { ...pkg.dependencies, "uc-config": `^${version}` };
+        if (!pkg.type)
+            pkg.type = "module";
+        await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+        result.packageJsonUpdated = true;
+    }
+    else {
+        result.skipped.push("package.json");
+    }
+    await put("tsconfig.json", JSON.stringify(tsconfig, null, 2) + "\n");
+    await put(".gitignore", gitignore);
+    await put("AGENTS.md", agents(version));
+    return result;
+}

package/dist/inventory.d.ts

@@ -0,0 +1,14 @@
+import { CoreClient } from "./client.js";
+import type { Config, ObjectValue } from "./model.js";
+export interface Inventory {
+    version: unknown;
+    collections: Record<string, ObjectValue[]>;
+    settings: Record<string, ObjectValue>;
+    unsupported: string[];
+}
+export declare function inventory(client: CoreClient): Promise<Inventory>;
+export declare function importConfig(client: CoreClient): Promise<{
+    config: Config;
+    warnings: string[];
+}>;
+export declare function generateBindings(inv: Inventory): string;