@slicervm/sdk 0.1.7 → 0.1.8

package/dist/index.d.cts

@@ -63,6 +63,7 @@ interface AgentHealth {
     agentVersion?: string;
     systemUptime?: number;
     userdataRan?: boolean;
+    userdataExitCode?: number;
 }
 interface VMLogs {
     hostname: string;
@@ -277,6 +278,91 @@ interface FSWatchEvent {
 interface ShutdownRequest {
     action?: 'shutdown' | 'reboot';
 }
+interface VMCommitOptions {
+    tags?: string[];
+    labels?: Record<string, string>;
+    cacheKey?: string;
+}
+interface VMCommitResponse {
+    hostname: string;
+    commitId: string;
+    status: string;
+    parentStatus?: string;
+    mode: string;
+    tags?: string[];
+    labels?: Record<string, string>;
+    cacheKey?: string;
+}
+interface VMCommitListOptions {
+    tags?: string[];
+    cacheKey?: string;
+    source?: string;
+    mode?: string;
+}
+interface VMCommitInfo {
+    commitId: string;
+    sourceHostname: string;
+    sourceHostGroup: string;
+    createdAt: string;
+    mode: string;
+    tags?: string[];
+    labels?: Record<string, string>;
+    cacheKey?: string;
+}
+interface VMCommitDeleteResponse {
+    commitId: string;
+    status: string;
+}
+/** Isolated-network policy override for a forked VM. */
+interface VMForkNetworkPolicy {
+    /** Omit to inherit; pass an empty array to clear the allow list. */
+    allow?: string[];
+    /** Omit to inherit; pass an empty array to clear the drop list. */
+    drop?: string[];
+}
+interface VMForkOptions {
+    /** Agent-readiness timeout in seconds. Forks always wait for the child agent. */
+    waitTimeoutSec?: number;
+    network?: VMForkNetworkPolicy;
+    tags?: string[];
+}
+interface VMForkResponse {
+    hostname: string;
+    sourceHostname: string;
+    commitId?: string;
+    status: string;
+    parentStatus?: string;
+    childStatus?: string;
+    mode: string;
+}
+interface VMNetworkPolicy {
+    allow: string[];
+    drop: string[];
+}
+interface VMNetworkDescription {
+    mode?: string;
+    policySource?: string;
+    hostGroup: VMNetworkPolicy;
+    override?: CreateVMNetworkPolicy;
+    effective: VMNetworkPolicy;
+}
+interface VMDescription {
+    hostname: string;
+    hostGroup?: string;
+    ip?: string;
+    ramBytes?: number;
+    cpus?: number;
+    createdAt?: string;
+    arch?: string;
+    tags?: string[];
+    status?: string;
+    persistent?: boolean;
+    storage?: string;
+    image?: string;
+    commitId?: string;
+    parentCommitId?: string;
+    network: VMNetworkDescription;
+}
 interface VMStat {
     hostname: string;
     ip: string;
@@ -544,6 +630,21 @@ interface VMInit {
     createdAt?: string;
     arch?: string;
 }
+declare class CommittedVM {
+    private readonly transport;
+    readonly hostname: string;
+    readonly hostGroup: string;
+    readonly commitId: string;
+    readonly status: string;
+    readonly parentStatus?: string;
+    readonly mode: VMCommitResponse['mode'];
+    readonly tags?: string[];
+    readonly labels?: Record<string, string>;
+    readonly cacheKey?: string;
+    constructor(transport: TransportClient, hostGroup: string, response: VMCommitResponse);
+    fork(opts?: VMForkOptions): Promise<VM>;
+    forkRaw(opts?: VMForkOptions): Promise<VMForkResponse>;
+}
 declare class VM {
     readonly hostname: string;
     readonly hostGroup: string;
@@ -557,6 +658,8 @@ declare class VM {
     delete(): Promise<void>;
     health(): Promise<AgentHealth>;
     logs(): Promise<VMLogs>;
+    /** Return configuration, fork lineage, and effective network policy. */
+    describe(): Promise<VMDescription>;
     waitForAgent(opts?: WaitOptions): Promise<AgentHealth>;
     waitForUserdata(opts?: WaitOptions): Promise<AgentHealth>;
     shutdown(req?: ShutdownRequest): Promise<void>;
@@ -567,6 +670,10 @@ declare class VM {
     suspend(): Promise<void>;
     /** Mac-only on current daemons. Throws `SlicerAPIError 404` on Linux. */
     restore(): Promise<void>;
+    /**
+     * Commit a stopped persistent VM disk into an immutable parent.
+     */
+    commit(opts?: VMCommitOptions): Promise<CommittedVM>;
     /**
      * Open one or more port forwards from the host to this VM. Each spec follows
      * the same syntax as `slicer vm forward -L`:
@@ -654,7 +761,7 @@ declare class VMBg {
 }
 
 /**
- * Top-level namespaces on SlicerClient: hostGroups, vms, secrets.
+ * Top-level namespaces on SlicerClient: hostGroups, vms, commits, secrets.
  * Keep control-plane operations here; per-VM operations live on the VM handle.
  */
 
@@ -686,6 +793,13 @@ declare class VMsAPI {
      */
     createRaw(hostGroup: string, req?: CreateVMRequest, opts?: CreateVMOptions): Promise<CreateVMResponse>;
 }
+declare class CommitsAPI {
+    private readonly transport;
+    constructor(transport: TransportClient);
+    list(opts?: VMCommitListOptions): Promise<VMCommitInfo[]>;
+    delete(commitId: string): Promise<VMCommitDeleteResponse>;
+    fork(commitId: string, opts?: VMForkOptions): Promise<VMForkResponse>;
+}
 declare class SecretsAPI {
     private readonly transport;
     constructor(transport: TransportClient);
@@ -719,10 +833,12 @@ declare class SecretsAPI {
  */
 
 /** Credential type for upstream injection. */
-type ProxySecretType = 'bearer' | 'basic';
+type ProxySecretType = 'bearer' | 'basic' | 'oauth-client-creds';
 declare const ProxySecretBearer: ProxySecretType;
 /** For basic auth, the secret value must be in `user:pass` form. */
 declare const ProxySecretBasic: ProxySecretType;
+/** OAuth 2.0 client credentials exchanged and renewed by the proxy host. */
+declare const ProxySecretOAuthClientCredentials: ProxySecretType;
 /** A registered proxy client. Tokens are never returned by list/get. */
 interface ProxyClient {
     name: string;
@@ -762,7 +878,9 @@ interface CreateProxySecretRequest {
     /**
      * Plaintext credential. For `bearer`, the raw token. For `basic`,
      * must be in `user:pass` form (the proxy base64-encodes it on the
-     * inner request).
+     * inner request). For `oauth-client-creds`, pass top-level JSON containing
+     * `token_endpoint`, `client_id`, and `client_secret`; optional `scope` is
+     * supported. The proxy obtains, caches, and renews the bearer host-side.
      */
     value: string;
 }
@@ -880,12 +998,13 @@ declare class ProxyAllowsAPI {
  * Shape:
  *   client.hostGroups.list() / find(name) / listVMs(name)
  *   client.vms.create(group, req, opts) → VM / get(name) / list() / stats() / attach(group, name)
+ *   client.commits.list() / fork(id) / delete(id)
  *   client.secrets.list / create / patch / delete
  *   client.getInfo()
  *
  * Per-VM operations live on the `VM` handle returned from `client.vms.create`
  * or `client.vms.attach`: `vm.exec`, `vm.execBuffered`, `vm.fs.*`,
- * `vm.pause/resume/suspend/restore/shutdown/relaunch`, `vm.health/logs`,
+ * `vm.pause/resume/suspend/restore/shutdown/relaunch`, `vm.commit/describe`, `vm.health/logs`,
  * `vm.waitForAgent/waitForUserdata`, `vm.delete`.
  */
 
@@ -895,6 +1014,7 @@ declare class SlicerClient {
     readonly transport: TransportClient;
     readonly hostGroups: HostGroupsAPI;
     readonly vms: VMsAPI;
+    readonly commits: CommitsAPI;
     readonly secrets: SecretsAPI;
     readonly proxy: ProxyAPI;
     constructor(opts: SlicerClientOptions);
@@ -968,4 +1088,4 @@ declare class SlicerShellSession {
     private teardown;
 }
 
-export { type AddProxyAllowRequest, type AddressMapping, type AgentHealth, type BgDeleteResponse, type BgExecInfo, type BgExecRequest, type BgExecResponse, type BgKillOptions, type BgKillResponse, type BgLogOptions, type BgWaitExitResponse, type CreateProxyClientOptions, type CreateProxySecretRequest, type CreateSecretRequest, type CreateVMNetworkPolicy, type CreateVMOptions, type CreateVMRequest, type CreateVMResponse, type DeleteResponse, type ExecFrame, type ExecRequest, type ExecResult, type ExecResultBinary, type ExecStdio, ExecStdioBase64, ExecStdioText, FRAME_TYPE_DATA, FRAME_TYPE_HEARTBEAT, FRAME_TYPE_SESSION_CLOSE, FRAME_TYPE_SHUTDOWN, FRAME_TYPE_WINDOW_SIZE, type FSEntry, type FSMkdirRequest, type FSWatchEvent, type FSWatchEventType, type FSWatchRequest, Forwarder, type ForwarderListener, type ForwarderOptions, GiB, type HostGroup, HostGroupsAPI, type ListOptions, MiB, NonRootUser, ProxyAPI, type ProxyAllowRule, ProxyAllowsAPI, type ProxyClient, type ProxyClientCreated, ProxyClientsAPI, type ProxySecret, ProxySecretBasic, ProxySecretBearer, type ProxySecretType, ProxySecretsAPI, type RemoveProxyAllowByTupleRequest, type Secret, SecretExistsError, SecretsAPI, type ShellSessionOptions, type ShutdownRequest, SlicerAPIError, SlicerClient, type SlicerClientOptions, type SlicerInfo, SlicerShellSession, type UpdateSecretRequest, VM, VMBg, VMFileSystem, type VMInfo, type VMInit, type VMLogs, type VMSnapshot, type VMStat, VMsAPI, type WaitOptions, type XTermLike, encodeFrame, parseAddressMapping, parseFrame, resolveTransport };
+export { type AddProxyAllowRequest, type AddressMapping, type AgentHealth, type BgDeleteResponse, type BgExecInfo, type BgExecRequest, type BgExecResponse, type BgKillOptions, type BgKillResponse, type BgLogOptions, type BgWaitExitResponse, CommitsAPI, CommittedVM, type CreateProxyClientOptions, type CreateProxySecretRequest, type CreateSecretRequest, type CreateVMNetworkPolicy, type CreateVMOptions, type CreateVMRequest, type CreateVMResponse, type DeleteResponse, type ExecFrame, type ExecRequest, type ExecResult, type ExecResultBinary, type ExecStdio, ExecStdioBase64, ExecStdioText, FRAME_TYPE_DATA, FRAME_TYPE_HEARTBEAT, FRAME_TYPE_SESSION_CLOSE, FRAME_TYPE_SHUTDOWN, FRAME_TYPE_WINDOW_SIZE, type FSEntry, type FSMkdirRequest, type FSWatchEvent, type FSWatchEventType, type FSWatchRequest, Forwarder, type ForwarderListener, type ForwarderOptions, GiB, type HostGroup, HostGroupsAPI, type ListOptions, MiB, NonRootUser, ProxyAPI, type ProxyAllowRule, ProxyAllowsAPI, type ProxyClient, type ProxyClientCreated, ProxyClientsAPI, type ProxySecret, ProxySecretBasic, ProxySecretBearer, ProxySecretOAuthClientCredentials, type ProxySecretType, ProxySecretsAPI, type RemoveProxyAllowByTupleRequest, type Secret, SecretExistsError, SecretsAPI, type ShellSessionOptions, type ShutdownRequest, SlicerAPIError, SlicerClient, type SlicerClientOptions, type SlicerInfo, SlicerShellSession, type UpdateSecretRequest, VM, VMBg, type VMCommitDeleteResponse, type VMCommitInfo, type VMCommitListOptions, type VMCommitOptions, type VMCommitResponse, type VMDescription, VMFileSystem, type VMForkNetworkPolicy, type VMForkOptions, type VMForkResponse, type VMInfo, type VMInit, type VMLogs, type VMNetworkDescription, type VMNetworkPolicy, type VMSnapshot, type VMStat, VMsAPI, type WaitOptions, type XTermLike, encodeFrame, parseAddressMapping, parseFrame, resolveTransport };

package/dist/index.d.ts

@@ -63,6 +63,7 @@ interface AgentHealth {
     agentVersion?: string;
     systemUptime?: number;
     userdataRan?: boolean;
+    userdataExitCode?: number;
 }
 interface VMLogs {
     hostname: string;
@@ -277,6 +278,91 @@ interface FSWatchEvent {
 interface ShutdownRequest {
     action?: 'shutdown' | 'reboot';
 }
+interface VMCommitOptions {
+    tags?: string[];
+    labels?: Record<string, string>;
+    cacheKey?: string;
+}
+interface VMCommitResponse {
+    hostname: string;
+    commitId: string;
+    status: string;
+    parentStatus?: string;
+    mode: string;
+    tags?: string[];
+    labels?: Record<string, string>;
+    cacheKey?: string;
+}
+interface VMCommitListOptions {
+    tags?: string[];
+    cacheKey?: string;
+    source?: string;
+    mode?: string;
+}
+interface VMCommitInfo {
+    commitId: string;
+    sourceHostname: string;
+    sourceHostGroup: string;
+    createdAt: string;
+    mode: string;
+    tags?: string[];
+    labels?: Record<string, string>;
+    cacheKey?: string;
+}
+interface VMCommitDeleteResponse {
+    commitId: string;
+    status: string;
+}
+/** Isolated-network policy override for a forked VM. */
+interface VMForkNetworkPolicy {
+    /** Omit to inherit; pass an empty array to clear the allow list. */
+    allow?: string[];
+    /** Omit to inherit; pass an empty array to clear the drop list. */
+    drop?: string[];
+}
+interface VMForkOptions {
+    /** Agent-readiness timeout in seconds. Forks always wait for the child agent. */
+    waitTimeoutSec?: number;
+    network?: VMForkNetworkPolicy;
+    tags?: string[];
+}
+interface VMForkResponse {
+    hostname: string;
+    sourceHostname: string;
+    commitId?: string;
+    status: string;
+    parentStatus?: string;
+    childStatus?: string;
+    mode: string;
+}
+interface VMNetworkPolicy {
+    allow: string[];
+    drop: string[];
+}
+interface VMNetworkDescription {
+    mode?: string;
+    policySource?: string;
+    hostGroup: VMNetworkPolicy;
+    override?: CreateVMNetworkPolicy;
+    effective: VMNetworkPolicy;
+}
+interface VMDescription {
+    hostname: string;
+    hostGroup?: string;
+    ip?: string;
+    ramBytes?: number;
+    cpus?: number;
+    createdAt?: string;
+    arch?: string;
+    tags?: string[];
+    status?: string;
+    persistent?: boolean;
+    storage?: string;
+    image?: string;
+    commitId?: string;
+    parentCommitId?: string;
+    network: VMNetworkDescription;
+}
 interface VMStat {
     hostname: string;
     ip: string;
@@ -544,6 +630,21 @@ interface VMInit {
     createdAt?: string;
     arch?: string;
 }
+declare class CommittedVM {
+    private readonly transport;
+    readonly hostname: string;
+    readonly hostGroup: string;
+    readonly commitId: string;
+    readonly status: string;
+    readonly parentStatus?: string;
+    readonly mode: VMCommitResponse['mode'];
+    readonly tags?: string[];
+    readonly labels?: Record<string, string>;
+    readonly cacheKey?: string;
+    constructor(transport: TransportClient, hostGroup: string, response: VMCommitResponse);
+    fork(opts?: VMForkOptions): Promise<VM>;
+    forkRaw(opts?: VMForkOptions): Promise<VMForkResponse>;
+}
 declare class VM {
     readonly hostname: string;
     readonly hostGroup: string;
@@ -557,6 +658,8 @@ declare class VM {
     delete(): Promise<void>;
     health(): Promise<AgentHealth>;
     logs(): Promise<VMLogs>;
+    /** Return configuration, fork lineage, and effective network policy. */
+    describe(): Promise<VMDescription>;
     waitForAgent(opts?: WaitOptions): Promise<AgentHealth>;
     waitForUserdata(opts?: WaitOptions): Promise<AgentHealth>;
     shutdown(req?: ShutdownRequest): Promise<void>;
@@ -567,6 +670,10 @@ declare class VM {
     suspend(): Promise<void>;
     /** Mac-only on current daemons. Throws `SlicerAPIError 404` on Linux. */
     restore(): Promise<void>;
+    /**
+     * Commit a stopped persistent VM disk into an immutable parent.
+     */
+    commit(opts?: VMCommitOptions): Promise<CommittedVM>;
     /**
      * Open one or more port forwards from the host to this VM. Each spec follows
      * the same syntax as `slicer vm forward -L`:
@@ -654,7 +761,7 @@ declare class VMBg {
 }
 
 /**
- * Top-level namespaces on SlicerClient: hostGroups, vms, secrets.
+ * Top-level namespaces on SlicerClient: hostGroups, vms, commits, secrets.
  * Keep control-plane operations here; per-VM operations live on the VM handle.
  */
 
@@ -686,6 +793,13 @@ declare class VMsAPI {
      */
     createRaw(hostGroup: string, req?: CreateVMRequest, opts?: CreateVMOptions): Promise<CreateVMResponse>;
 }
+declare class CommitsAPI {
+    private readonly transport;
+    constructor(transport: TransportClient);
+    list(opts?: VMCommitListOptions): Promise<VMCommitInfo[]>;
+    delete(commitId: string): Promise<VMCommitDeleteResponse>;
+    fork(commitId: string, opts?: VMForkOptions): Promise<VMForkResponse>;
+}
 declare class SecretsAPI {
     private readonly transport;
     constructor(transport: TransportClient);
@@ -719,10 +833,12 @@ declare class SecretsAPI {
  */
 
 /** Credential type for upstream injection. */
-type ProxySecretType = 'bearer' | 'basic';
+type ProxySecretType = 'bearer' | 'basic' | 'oauth-client-creds';
 declare const ProxySecretBearer: ProxySecretType;
 /** For basic auth, the secret value must be in `user:pass` form. */
 declare const ProxySecretBasic: ProxySecretType;
+/** OAuth 2.0 client credentials exchanged and renewed by the proxy host. */
+declare const ProxySecretOAuthClientCredentials: ProxySecretType;
 /** A registered proxy client. Tokens are never returned by list/get. */
 interface ProxyClient {
     name: string;
@@ -762,7 +878,9 @@ interface CreateProxySecretRequest {
     /**
      * Plaintext credential. For `bearer`, the raw token. For `basic`,
      * must be in `user:pass` form (the proxy base64-encodes it on the
-     * inner request).
+     * inner request). For `oauth-client-creds`, pass top-level JSON containing
+     * `token_endpoint`, `client_id`, and `client_secret`; optional `scope` is
+     * supported. The proxy obtains, caches, and renews the bearer host-side.
      */
     value: string;
 }
@@ -880,12 +998,13 @@ declare class ProxyAllowsAPI {
  * Shape:
  *   client.hostGroups.list() / find(name) / listVMs(name)
  *   client.vms.create(group, req, opts) → VM / get(name) / list() / stats() / attach(group, name)
+ *   client.commits.list() / fork(id) / delete(id)
  *   client.secrets.list / create / patch / delete
  *   client.getInfo()
  *
  * Per-VM operations live on the `VM` handle returned from `client.vms.create`
  * or `client.vms.attach`: `vm.exec`, `vm.execBuffered`, `vm.fs.*`,
- * `vm.pause/resume/suspend/restore/shutdown/relaunch`, `vm.health/logs`,
+ * `vm.pause/resume/suspend/restore/shutdown/relaunch`, `vm.commit/describe`, `vm.health/logs`,
  * `vm.waitForAgent/waitForUserdata`, `vm.delete`.
  */
 
@@ -895,6 +1014,7 @@ declare class SlicerClient {
     readonly transport: TransportClient;
     readonly hostGroups: HostGroupsAPI;
     readonly vms: VMsAPI;
+    readonly commits: CommitsAPI;
     readonly secrets: SecretsAPI;
     readonly proxy: ProxyAPI;
     constructor(opts: SlicerClientOptions);
@@ -968,4 +1088,4 @@ declare class SlicerShellSession {
     private teardown;
 }
 
-export { type AddProxyAllowRequest, type AddressMapping, type AgentHealth, type BgDeleteResponse, type BgExecInfo, type BgExecRequest, type BgExecResponse, type BgKillOptions, type BgKillResponse, type BgLogOptions, type BgWaitExitResponse, type CreateProxyClientOptions, type CreateProxySecretRequest, type CreateSecretRequest, type CreateVMNetworkPolicy, type CreateVMOptions, type CreateVMRequest, type CreateVMResponse, type DeleteResponse, type ExecFrame, type ExecRequest, type ExecResult, type ExecResultBinary, type ExecStdio, ExecStdioBase64, ExecStdioText, FRAME_TYPE_DATA, FRAME_TYPE_HEARTBEAT, FRAME_TYPE_SESSION_CLOSE, FRAME_TYPE_SHUTDOWN, FRAME_TYPE_WINDOW_SIZE, type FSEntry, type FSMkdirRequest, type FSWatchEvent, type FSWatchEventType, type FSWatchRequest, Forwarder, type ForwarderListener, type ForwarderOptions, GiB, type HostGroup, HostGroupsAPI, type ListOptions, MiB, NonRootUser, ProxyAPI, type ProxyAllowRule, ProxyAllowsAPI, type ProxyClient, type ProxyClientCreated, ProxyClientsAPI, type ProxySecret, ProxySecretBasic, ProxySecretBearer, type ProxySecretType, ProxySecretsAPI, type RemoveProxyAllowByTupleRequest, type Secret, SecretExistsError, SecretsAPI, type ShellSessionOptions, type ShutdownRequest, SlicerAPIError, SlicerClient, type SlicerClientOptions, type SlicerInfo, SlicerShellSession, type UpdateSecretRequest, VM, VMBg, VMFileSystem, type VMInfo, type VMInit, type VMLogs, type VMSnapshot, type VMStat, VMsAPI, type WaitOptions, type XTermLike, encodeFrame, parseAddressMapping, parseFrame, resolveTransport };
+export { type AddProxyAllowRequest, type AddressMapping, type AgentHealth, type BgDeleteResponse, type BgExecInfo, type BgExecRequest, type BgExecResponse, type BgKillOptions, type BgKillResponse, type BgLogOptions, type BgWaitExitResponse, CommitsAPI, CommittedVM, type CreateProxyClientOptions, type CreateProxySecretRequest, type CreateSecretRequest, type CreateVMNetworkPolicy, type CreateVMOptions, type CreateVMRequest, type CreateVMResponse, type DeleteResponse, type ExecFrame, type ExecRequest, type ExecResult, type ExecResultBinary, type ExecStdio, ExecStdioBase64, ExecStdioText, FRAME_TYPE_DATA, FRAME_TYPE_HEARTBEAT, FRAME_TYPE_SESSION_CLOSE, FRAME_TYPE_SHUTDOWN, FRAME_TYPE_WINDOW_SIZE, type FSEntry, type FSMkdirRequest, type FSWatchEvent, type FSWatchEventType, type FSWatchRequest, Forwarder, type ForwarderListener, type ForwarderOptions, GiB, type HostGroup, HostGroupsAPI, type ListOptions, MiB, NonRootUser, ProxyAPI, type ProxyAllowRule, ProxyAllowsAPI, type ProxyClient, type ProxyClientCreated, ProxyClientsAPI, type ProxySecret, ProxySecretBasic, ProxySecretBearer, ProxySecretOAuthClientCredentials, type ProxySecretType, ProxySecretsAPI, type RemoveProxyAllowByTupleRequest, type Secret, SecretExistsError, SecretsAPI, type ShellSessionOptions, type ShutdownRequest, SlicerAPIError, SlicerClient, type SlicerClientOptions, type SlicerInfo, SlicerShellSession, type UpdateSecretRequest, VM, VMBg, type VMCommitDeleteResponse, type VMCommitInfo, type VMCommitListOptions, type VMCommitOptions, type VMCommitResponse, type VMDescription, VMFileSystem, type VMForkNetworkPolicy, type VMForkOptions, type VMForkResponse, type VMInfo, type VMInit, type VMLogs, type VMNetworkDescription, type VMNetworkPolicy, type VMSnapshot, type VMStat, VMsAPI, type WaitOptions, type XTermLike, encodeFrame, parseAddressMapping, parseFrame, resolveTransport };