incus-ts 0.1.0 → 0.1.2

package/README.md

@@ -1,63 +1,183 @@
 # incus-ts
 
-First step of a Bun-first TypeScript port of the Incus Go client.
+Lightweight Bun-first TypeScript client for Incus.
 
-Current status: core runtime is implemented for transport, raw requests, server,
-operations, images, and a practical subset of instance operations. Other
-domains are scaffolded and currently return explicit "not implemented yet"
-errors.
+The API is instance-handle oriented: get a handle with
+`client.instances.instance(name)`, then call `.exec()`, `.setState()`, `.remove()`, etc.
 
-## Goals
+Operation-returning calls are awaitable by default.
 
-- Keep setup lightweight (Bun for install/build/test).
-- Preserve Incus Go client capability domains.
-- Provide a Gondolin-like ergonomic TypeScript surface:
-  - static factories (`Incus.connect*`)
-  - grouped resource APIs (`client.instances`, `client.networks`, ...)
-  - chainable context scoping (`client.project(...).target(...)`)
+## Mental Model
 
-## Quick look
+1. Connect once (`Incus.connect*`).
+2. Use collection APIs for listing/creating (`client.instances.*`).
+3. Use a per-instance handle for day-to-day work (`client.instances.instance(name)`).
+
+## Quick Start
 
 ```ts
 import { Incus } from "incus-ts";
 
-const client = await Incus.connect("https://incus.example");
+const client = await Incus.connectUnix(); // default: /var/lib/incus/unix.socket
+const instance = client.instances.instance("my-container");
+
+const proc = instance.exec(
+  { command: ["sh", "-lc", "echo hello from incus-ts"], interactive: false },
+  { stdout: "pipe", stderr: "pipe" },
+);
+
+for await (const chunk of proc) {
+  process.stdout.write(new TextDecoder().decode(chunk));
+}
+
+const result = await proc;
+console.log(result.exitCode, result.ok);
+```
+
+## Common Snippets (From E2E Flow)
 
-const scoped = client.project("my-project").target("node-1");
+### 1. Create a container (same base image style as e2e/gondolin setup)
 
-await scoped.instances.list({ type: "container", allProjects: false });
-await scoped.images.aliases.get("alpine/3.20");
+```ts
+import { Incus } from "incus-ts";
+
+const client = await Incus.connectUnix();
+const name = `incus-ts-demo-${Date.now().toString(36)}`;
+
+await client.instances.create({
+  name,
+  type: "container",
+  source: {
+    type: "image",
+    mode: "pull",
+    server: "https://images.linuxcontainers.org",
+    protocol: "simplestreams",
+    alias: "alpine/3.20",
+  },
+});
+```
+
+### 2. Start it
+
+```ts
+const instance = client.instances.instance(name);
+await instance.setState({ action: "start", timeout: 180 });
+```
+
+### 3. Stream output while command is running
+
+```ts
+const instance = client.instances.instance(name);
+
+const proc = instance.exec(
+  { command: ["sh", "-lc", "echo stream:1; cat >/dev/null; echo stream:2"], interactive: false },
+  { stdout: "pipe", stderr: "pipe" },
+);
 
-const instance = scoped.instances.instance("my-container");
-const proc = instance.exec({ command: ["sh", "-lc", "echo hello"] }, { stdout: "pipe" });
 for await (const chunk of proc) {
   process.stdout.write(new TextDecoder().decode(chunk));
 }
+
 const result = await proc;
-console.log(result.exitCode);
+console.log(result.exitCode, result.ok);
+```
+
+### 4. Run a network check inside the container
+
+```ts
+const instance = client.instances.instance(name);
+const decoder = new TextDecoder();
+let stdout = "";
+let stderr = "";
+
+const net = instance.exec(
+  {
+    command: [
+      "sh",
+      "-lc",
+      "GW=$(ip route | awk '/default/ {print $3; exit}'); "
+        + "ping -c 1 -W 2 \"${GW:-192.168.100.1}\" >/tmp/ping.out 2>&1; "
+        + "rc=$?; cat /tmp/ping.out; "
+        + "if [ \"$rc\" -eq 0 ]; then echo __PING_OK__; fi; "
+        + "exit \"$rc\"",
+    ],
+    interactive: false,
+  },
+  { stdout: "pipe", stderr: "pipe" },
+);
+
+const readStdout = (async () => {
+  for await (const chunk of net.stdout) stdout += decoder.decode(chunk, { stream: true });
+  stdout += decoder.decode();
+})();
+const readStderr = (async () => {
+  for await (const chunk of net.stderr) stderr += decoder.decode(chunk, { stream: true });
+  stderr += decoder.decode();
+})();
+
+const netResult = await net;
+await Promise.all([readStdout, readStderr]);
+if (!netResult.ok || !`${stdout}\n${stderr}`.includes("__PING_OK__")) {
+  throw new Error("network check failed");
+}
+```
+
+### 5. Cleanup
+
+```ts
+const instance = client.instances.instance(name);
+
+try {
+  await instance.setState({ action: "stop", timeout: 30, force: true });
+} catch {
+  // Instance might already be stopped.
+}
+
+await instance.remove();
+client.disconnect();
+```
+
+### 6. Snapshot + restore
+
+```ts
+const instance = client.instances.instance("my-container");
+
+await instance.snapshots.create({ name: "snap0" });
+await instance.restore("snap0");
+```
+
+### 7. Fork (copy) an instance
+
+```ts
+const source = client.instances.instance("my-container");
+
+// Clone current state
+await source.fork("my-container-copy");
+
+// Clone from a specific snapshot
+await source.fork("my-container-from-snap", {
+  fromSnapshot: "snap0",
+});
 ```
 
-## Implemented now
+## Implemented
 
-- `connection`, `raw`
-- `server`
-- `operations`
-- `images` + `images.aliases` (simple streams remains unimplemented)
-- `instances` collection + per-instance handles (`instances.instance(name)`) for
-  CRUD/state/exec/console/metadata/logs/files with websocket exec stream attach over Unix sockets
+- `connection`, `raw`, `server`, `operations`
+- `images` + `images.aliases` (simple-streams runtime methods are still scaffolded)
+- `instances` collection + instance handles (`instances.instance(name)`) with:
+  - CRUD/state
+  - snapshots (`create`, `list`, `get`, `update`, `rename`, `remove`, `restore`)
+  - `exec` (Unix-socket websocket attach, async streaming, promise-style completion)
+  - `logs`, `files`, `metadata`, `console`
 
-## Sketched but not implemented yet
+## Still Scaffolded
 
-- `certificates`
-- `events`
-- `networks` and nested groups
-- `profiles`, `projects`
-- `storage` and nested groups
-- `cluster`
-- `warnings`
-- `instances.templates`, `instances.snapshots`, `instances.backups`
+- `certificates`, `events`
+- `networks`, `profiles`, `projects`
+- `storage`, `cluster`, `warnings`
+- `instances.templates`, `instances.backups`
 
-## Scripts
+## Bun Scripts
 
 - `bun run typecheck`
 - `bun run test`