feat(api): add autogenerated stat endpoint from Stainless

Cherry-picked from stainless/preview/feature/hypeman-cp

- Add client.instances.stat() method
- Add PathInfo response type
- Add InstanceStatParams query parameters

Author: rgarcia

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 29
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fhypeman-95df8b193133def744aa61dc372f286663ffc20d833488d242fa288af65adc39.yml
-openapi_spec_hash: 833120a235ecb298688c2fb1122b3574
-config_hash: 48d3be2bdbf56b770c9695a338382558
+configured_endpoints: 30
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fhypeman-28e78b73c796f9ee866671ed946402b5d569e683c3207d57c9143eb7d6f83fb6.yml
+openapi_spec_hash: fce0ac8713369a5f048bac684ed34fc8
+config_hash: f65a6a2bcef49a9f623212f9de6d6f6f

api.md

@@ -27,6 +27,7 @@ Methods:
 Types:
 
 - <code><a href="./src/resources/instances/instances.ts">Instance</a></code>
+- <code><a href="./src/resources/instances/instances.ts">PathInfo</a></code>
 - <code><a href="./src/resources/instances/instances.ts">PortMapping</a></code>
 - <code><a href="./src/resources/instances/instances.ts">VolumeMount</a></code>
 - <code><a href="./src/resources/instances/instances.ts">InstanceListResponse</a></code>
@@ -42,6 +43,7 @@ Methods:
 - <code title="post /instances/{id}/restore">client.instances.<a href="./src/resources/instances/instances.ts">restore</a>(id) -> Instance</code>
 - <code title="post /instances/{id}/standby">client.instances.<a href="./src/resources/instances/instances.ts">standby</a>(id) -> Instance</code>
 - <code title="post /instances/{id}/start">client.instances.<a href="./src/resources/instances/instances.ts">start</a>(id) -> Instance</code>
+- <code title="get /instances/{id}/stat">client.instances.<a href="./src/resources/instances/instances.ts">stat</a>(id, { ...params }) -> PathInfo</code>
 - <code title="post /instances/{id}/stop">client.instances.<a href="./src/resources/instances/instances.ts">stop</a>(id) -> Instance</code>
 
 ## Volumes

src/client.ts

@@ -49,7 +49,9 @@ import {
   InstanceListResponse,
   InstanceLogsParams,
   InstanceLogsResponse,
+  InstanceStatParams,
   Instances,
+  PathInfo,
   PortMapping,
   VolumeMount,
 } from './resources/instances/instances';
@@ -780,12 +782,14 @@ export declare namespace Hypeman {
   export {
     Instances as Instances,
     type Instance as Instance,
+    type PathInfo as PathInfo,
     type PortMapping as PortMapping,
     type VolumeMount as VolumeMount,
     type InstanceListResponse as InstanceListResponse,
     type InstanceLogsResponse as InstanceLogsResponse,
     type InstanceCreateParams as InstanceCreateParams,
     type InstanceLogsParams as InstanceLogsParams,
+    type InstanceStatParams as InstanceStatParams,
   };
 
   export {

src/resources/index.ts

@@ -23,12 +23,14 @@ export {
 export {
   Instances,
   type Instance,
+  type PathInfo,
   type PortMapping,
   type VolumeMount,
   type InstanceListResponse,
   type InstanceLogsResponse,
   type InstanceCreateParams,
   type InstanceLogsParams,
+  type InstanceStatParams,
 } from './instances/instances';
 export {
   Volumes,

src/resources/instances/index.ts

@@ -3,11 +3,13 @@
 export {
   Instances,
   type Instance,
+  type PathInfo,
   type PortMapping,
   type VolumeMount,
   type InstanceListResponse,
   type InstanceLogsResponse,
   type InstanceCreateParams,
   type InstanceLogsParams,
+  type InstanceStatParams,
 } from './instances';
 export { Volumes, type VolumeAttachParams, type VolumeDetachParams } from './volumes';

src/resources/instances/instances.ts

@@ -131,6 +131,21 @@ export class Instances extends APIResource {
     return this._client.post(path`/instances/${id}/start`, options);
   }
 
+  /**
+   * Returns information about a path in the guest filesystem. Useful for checking if
+   * a path exists, its type, and permissions before performing file operations.
+   *
+   * @example
+   * ```ts
+   * const pathInfo = await client.instances.stat('id', {
+   *   path: 'path',
+   * });
+   * ```
+   */
+  stat(id: string, query: InstanceStatParams, options?: RequestOptions): APIPromise<PathInfo> {
+    return this._client.get(path`/instances/${id}/stat`, { query, ...options });
+  }
+
   /**
    * Stop instance (graceful shutdown)
    *
@@ -261,6 +276,49 @@ export namespace Instance {
   }
 }
 
+export interface PathInfo {
+  /**
+   * Whether the path exists
+   */
+  exists: boolean;
+
+  /**
+   * Error message if stat failed (e.g., permission denied). Only set when exists is
+   * false due to an error rather than the path not existing.
+   */
+  error?: string | null;
+
+  /**
+   * True if this is a directory
+   */
+  is_dir?: boolean;
+
+  /**
+   * True if this is a regular file
+   */
+  is_file?: boolean;
+
+  /**
+   * True if this is a symbolic link (only set when follow_links=false)
+   */
+  is_symlink?: boolean;
+
+  /**
+   * Symlink target path (only set when is_symlink=true)
+   */
+  link_target?: string | null;
+
+  /**
+   * File mode (Unix permissions)
+   */
+  mode?: number;
+
+  /**
+   * File size in bytes
+   */
+  size?: number;
+}
+
 export interface PortMapping {
   /**
    * Port in the guest VM
@@ -393,17 +451,31 @@ export interface InstanceLogsParams {
   tail?: number;
 }
 
+export interface InstanceStatParams {
+  /**
+   * Path to stat in the guest filesystem
+   */
+  path: string;
+
+  /**
+   * Follow symbolic links (like stat vs lstat)
+   */
+  follow_links?: boolean;
+}
+
 Instances.Volumes = Volumes;
 
 export declare namespace Instances {
   export {
     type Instance as Instance,
+    type PathInfo as PathInfo,
     type PortMapping as PortMapping,
     type VolumeMount as VolumeMount,
     type InstanceListResponse as InstanceListResponse,
     type InstanceLogsResponse as InstanceLogsResponse,
     type InstanceCreateParams as InstanceCreateParams,
     type InstanceLogsParams as InstanceLogsParams,
+    type InstanceStatParams as InstanceStatParams,
   };
 
   export {

tests/api-resources/instances/instances.test.ts

@@ -143,6 +143,23 @@ describe('resource instances', () => {
     expect(dataAndResponse.response).toBe(rawResponse);
   });
 
+  // Prism tests are disabled
+  test.skip('stat: only required params', async () => {
+    const responsePromise = client.instances.stat('id', { path: 'path' });
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+
+  // Prism tests are disabled
+  test.skip('stat: required and optional params', async () => {
+    const response = await client.instances.stat('id', { path: 'path', follow_links: true });
+  });
+
   // Prism tests are disabled
   test.skip('stop', async () => {
     const responsePromise = client.instances.stop('id');