Machine specs

import { Boxd, Machine, team, github, slack, jira, claude, secrets } from "@boxd-sh/sdk";

const boxd = new Boxd({ apiKey: "bxd_..." });

// A secret that reaches no machine until a spec lists it.
await boxd.secrets.set("NPM_TOKEN", "npm_...", { scope: "unattached", org: "acme" });

// What every engineering machine has.
const engineering = Machine.spec()
  .from(team("eng"))                          // the eng team's default snapshot
  .network("eng")
  .label("team", "eng")
  .env("NODE_ENV", "development")
  .packages("apt-get update", "apt-get install -y nginx")
  .with(github({ shared: "eng-bot" }), claude());

// Mike's machine: the engineering spec, a size, and what he needs on top.
const mike = engineering
  .size("2x8")
  .with(slack(), jira({ shared: "jira" }), secrets("NPM_TOKEN"));

const m = await boxd.machines.create({ name: "mike-dev", org: "acme", spec: mike });
m.spec;          // the spec as it stands now
m.createdSpec;   // the spec it was created with, never changed

from boxd import Boxd, Machine, team, github, slack, jira, claude, secrets

boxd = Boxd(api_key="bxd_...")

# A secret that reaches no machine until a spec lists it.
boxd.secrets.set("NPM_TOKEN", "npm_...", scope="unattached", org="acme")

# What every engineering machine has.
engineering = (
    Machine.spec()
    .from_(team("eng"))                       # the eng team's default snapshot
    .network("eng")
    .label("team", "eng")
    .env("NODE_ENV", "development")
    .packages("apt-get update", "apt-get install -y nginx")
    .with_(github(shared="eng-bot"), claude())
)

# Mike's machine: the engineering spec, a size, and what he needs on top.
mike = engineering.size("2x8").with_(slack(), jira(shared="jira"), secrets("NPM_TOKEN"))

m = boxd.machines.create("mike-dev", org="acme", spec=mike)
m.spec           # the spec as it stands now
m.created_spec   # the spec it was created with, never changed

import type { MachineSpecPiece } from "@boxd-sh/sdk";

// Any integration in the catalog, not only the four with helpers.
const notion: MachineSpecPiece = { connections: { notion: "personal" } };

// A piece is just data, so a function can build one.
const service = (name: string): MachineSpecPiece => ({
  labels: { service: name },
  env: { SERVICE_NAME: name },
  packages: [`git clone https://github.com/acme/${name} /srv/${name}`],
});

const spec = engineering.with(notion, service("billing"));

# Any integration in the catalog, not only the four with helpers.
notion = {"connections": {"notion": "personal"}}

# A piece is just data, so a function can build one.
def service(name: str) -> dict:
    return {
        "labels": {"service": name},
        "env": {"SERVICE_NAME": name},
        "packages": [f"git clone https://github.com/acme/{name} /srv/{name}"],
    }

spec = engineering.with_(notion, service("billing"))

await boxd.machines.create({ name: "mike-dev", org: "acme", spec: mike });

// A snapshot base restores the snapshot.
await boxd.machines.create({ name: "api-1", spec: Machine.spec().from(snapshot("api-base")).label("env", "dev") });

// Or add a spec to a snapshot's own.
await boxd.machines.create({ name: "api-2", fromSnapshot: "api-base", spec: Machine.spec().network("ops") });

boxd.machines.create("mike-dev", org="acme", spec=mike)

# A snapshot base restores the snapshot.
boxd.machines.create("api-1", spec=Machine.spec().from_(snapshot("api-base")).label("env", "dev"))

# Or add a spec to a snapshot's own.
boxd.machines.create("api-2", from_snapshot="api-base", spec=Machine.spec().network("ops"))

// The org's: only org owners and admins can set, move or delete one.
await boxd.secrets.set("NPM_TOKEN", "npm_...", { scope: "unattached", org: "acme" });

// Your own, in that org.
await boxd.secrets.set("MY_TOKEN", "...", { scope: "private-unattached", org: "acme" });

const m = await boxd.machines.create({ name: "mike-dev", org: "acme", spec: engineering.with(secrets("NPM_TOKEN")) });
(await boxd.secrets.list({ org: "acme" })).map((s) => [s.name, s.scope, s.boundMachines]);

# The org's: only org owners and admins can set, move or delete one.
boxd.secrets.set("NPM_TOKEN", "npm_...", scope="unattached", org="acme")

# Your own, in that org.
boxd.secrets.set("MY_TOKEN", "...", scope="private-unattached", org="acme")

m = boxd.machines.create("mike-dev", org="acme", spec=engineering.with_(secrets("NPM_TOKEN")))
[(s.name, s.scope, s.bound_machines) for s in boxd.secrets.list(org="acme")]

const { members } = await boxd.orgs.getMembers("acme");
const mikeId = members.find((x) => x.githubUsername === "mike")!.userId;

const m = await boxd.machines.create({
  name: "mike-dev",
  org: "acme",                                // required: the org the machine is for
  spec: engineering.size("2x8").assignTo(mikeId),
});
m.id; m.name;                                 // all you get back: the machine is Mike's

roster = boxd.orgs.get_members("acme")
mike_id = next(x.user_id for x in roster.members if x.github_username == "mike")

m = boxd.machines.create(
    "mike-dev",
    org="acme",                                # required: the org the machine is for
    spec=engineering.size("2x8").assign_to(mike_id),
)
m.id, m.name                                   # all you get back: the machine is Mike's

const m = await boxd.machines.get("mike-dev");
for (const r of m.requirements) {
  // { kind: "connection", name: "jira", scope: "shared", tag: "jira", met: false, canFix: true, reason: null }
  console.log(r.name, r.met ? "connected" : r.canFix ? "connect it" : r.reason ?? "ask an org admin");
}

m = boxd.machines.get("mike-dev")
for r in m.requirements:
    # kind="connection" name="jira" scope="shared" tag="jira" met=False can_fix=True reason=None
    print(r.name, "connected" if r.met else "connect it" if r.can_fix else r.reason or "ask an org admin")

const m = await boxd.machines.get("mike-dev");
for (const p of m.packages) {
  // { command: "apt-get install -y nginx", state: "failed", exitCode: 100, outputTail: "E: Unable to locate…", reason: null, … }
  console.log(p.state, p.exitCode, p.command);
}

// Run the failed command and the ones after it again:
await boxd.machines.updateSpec("mike-dev", {}, { retryPackages: true });

// Or replace it: the old one is skipped, the corrected one and the rest run.
await boxd.machines.updateSpec("mike-dev", {
  packages: ["apt-get update", "apt-get install -y nginx-light"],
});

m = boxd.machines.get("mike-dev")
for p in m.packages:
    # command="apt-get install -y nginx" state="failed" exit_code=100 output_tail="E: Unable to locate…" reason=None …
    print(p.state, p.exit_code, p.command)

# Run the failed command and the ones after it again:
boxd.machines.update_spec("mike-dev", {}, retry_packages=True)

# Or replace it: the old one is skipped, the corrected one and the rest run.
boxd.machines.update_spec(
    "mike-dev", {"packages": ["apt-get update", "apt-get install -y nginx-light"]}
)

// A patch: a field left out is untouched, a scalar replaces, maps merge key by
// key (null removes a key), a list replaces the whole list, null removes a field.
await boxd.machines.updateSpec("mike-dev", {
  labels: { owner: "mike", team: null },
  networks: ["eng", "ops"],
  packages: ["apt-get install -y nginx", "npm i -g pnpm"],
});

// A builder: reads the spec, adds with the merge rules, sends the difference.
await boxd.machines.updateSpec("mike-dev", (s) => s.network("ops").env("LOG_LEVEL", "debug"));

// A dry run: the diff, nothing changed.
const diff = await boxd.machines.updateSpec("mike-dev", { size: "4x16" }, { dryRun: true });
for (const c of diff.changes) console.log(c.field, c.apply, c.note, c.warnings);
if (diff.rebootRequired) {
  await boxd.machines.updateSpec("mike-dev", { size: "4x16" }, { reboot: true });
}

# A patch: a field left out is untouched, a scalar replaces, maps merge key by
# key (None removes a key), a list replaces the whole list, None removes a field.
boxd.machines.update_spec("mike-dev", {
    "labels": {"owner": "mike", "team": None},
    "networks": ["eng", "ops"],
    "packages": ["apt-get install -y nginx", "npm i -g pnpm"],
})

# A builder: reads the spec, adds with the merge rules, sends the difference.
boxd.machines.update_spec("mike-dev", lambda s: s.network("ops").env("LOG_LEVEL", "debug"))

# A dry run: the diff, nothing changed.
diff = boxd.machines.update_spec("mike-dev", {"size": "4x16"}, dry_run=True)
for c in diff.changes:
    print(c.field, c.apply, c.note, c.warnings)
if diff.reboot_required:
    boxd.machines.update_spec("mike-dev", {"size": "4x16"}, reboot=True)