@samyx/preview-stacks-client 0.32.0 → 0.33.1

package/dist/index.d.ts

@@ -25,7 +25,7 @@
  * polling a job without a terminal-state list (`queued` is not running and not finished either), or
  * treating `readiness.state === 'watching'` as an error rather than "ask again".
  */
-import type { CancelStack, DeliveryRow, DeploymentRow, Health, HostVar, Job, Kind, Logs, Me, NotifierRow, Readiness, Role, Runtime, ShareLink, ShareView, SpecMeta, SsoConfig, SsoConfigResponse, SwarmInfo, User } from './types.ts';
+import type { CancelStack, DeliveryRow, DeploymentRow, Health, HostSettings, HostVar, Job, Kind, Logs, Me, NotifierRow, Readiness, Role, Runtime, SettingKey, SettingWritten, ShareLink, ShareView, SpecMeta, SsoConfig, SsoConfigResponse, SwarmInfo, User } from './types.ts';
 export * from './types.ts';
 /** A non-2xx answer. `body` is the parsed JSON, which is where the server's own message lives. */
 export declare class PstackError extends Error {
@@ -193,9 +193,13 @@ export declare function createClient(opts: ClientOptions): {
     users: {
         list: () => Promise<User[]>;
         /**
-         * An ABSENT `role` means VIEWER — the least privilege, not the most. This route used to create
-         * an administrator every time; a script that relied on that must now say `role: 'admin'` and
-         * mean it. A role outside the four is a 400 rather than a silently powerless account.
+         * An ABSENT `role` means the host's `default_role` setting — `viewer` on a host where nobody
+         * has changed it, which is what this used to mean unconditionally. It is still the least
+         * privilege by default and never admin by omission, but it is now an OPERATOR'S choice
+         * (`settings.set('default_role', …)`), so a script that wants a specific role must name it
+         * rather than rely on the host's. This route used to create an administrator every time; a
+         * script that relied on THAT must say `role: 'admin'` and mean it. A role outside the four is
+         * a 400 rather than a silently powerless account.
          */
         create: (body: {
             username: string;
@@ -330,6 +334,27 @@ export declare function createClient(opts: ClientOptions): {
             deleted: string;
         }>;
     };
+    /**
+     * The two host settings that change at RUNTIME: the running-job cap and the role an account
+     * created with no role named gets.
+     *
+     * Reading is viewer's; writing is per KEY, not per route — `max_jobs` is maintainer's and
+     * `default_role` is admin's, and each row says which in `minRole`. The read also says where
+     * each value came from (`source`), which is the only way to tell a value you set from one your
+     * environment is supplying.
+     */
+    settings: {
+        get: () => Promise<HostSettings>;
+        /**
+         * Store one. Refused (400) for an unknown key or a value the server will not take —
+         * `max_jobs` is an integer ≥ 1, `default_role` one of the four roles.
+         *
+         * `max_jobs` takes effect on the NEXT dispatch, with no restart: raising it starts a job that
+         * was waiting for a slot, and LOWERING IT CANCELS NOTHING — the jobs already running run to
+         * completion. The `note` in the response says so; print it rather than paraphrasing.
+         */
+        set: (key: SettingKey, value: number | Role) => Promise<SettingWritten>;
+    };
     /**
      * Poll a job until it reaches a terminal state.
      *

package/dist/index.js

@@ -132,6 +132,10 @@ function createClient(opts) {
       put: (name, value, secret = false) => put(`/api/host-vars/${enc(name)}`, { value, secret }),
       remove: (name) => del(`/api/host-vars/${enc(name)}`)
     },
+    settings: {
+      get: () => get("/api/settings"),
+      set: (key, value) => put(`/api/settings/${enc(key)}`, { value })
+    },
     async waitForJob(jobId, o = {}) {
       const interval = o.intervalMs ?? 2000;
       const deadline = Date.now() + (o.timeoutMs ?? 30 * 60000);

package/dist/types.d.ts

@@ -360,6 +360,50 @@ export type Me = {
         expiresAt?: number | null;
     };
 };
+/**
+ * The two settings that can be changed at RUNTIME, without restarting the container. The server
+ * refuses any other key rather than storing it, so this union is the whole surface.
+ */
+export type SettingKey = 'max_jobs' | 'default_role';
+/**
+ * One setting, as read and as returned by a write.
+ *
+ * `source` says where the value came from: `db` (someone set it through the API), `env`
+ * (`PSTACK_MAX_JOBS`), or `default` (what the binary ships with). Precedence is **database >
+ * environment > built-in default** — the environment variable is the DEFAULT, not the authority, so
+ * a stored value survives the next restart and a host that never sets one behaves exactly as it did
+ * before this existed.
+ *
+ * `minRole` is the least role that may WRITE this key, served from the server's own permission
+ * table: `max_jobs` is maintainer's, `default_role` is admin's. Reading is viewer's. Treat a name
+ * this build does not recognise as the most privileged, never the least.
+ */
+export type SettingRow = {
+    key: SettingKey;
+    /** A number for `max_jobs`; a role name for `default_role`. */
+    value: number | string;
+    source: 'db' | 'env' | 'default';
+    minRole: string;
+};
+export type HostSettings = {
+    settings: SettingRow[];
+    /** `null` when `PSTACK_MAX_JOBS` is unset — never `0`, which the server reads as unset. */
+    env: {
+        PSTACK_MAX_JOBS: number | null;
+    };
+    precedence: string;
+};
+/**
+ * What a write answers: the fresh row (`source` is now `db`), and for `max_jobs` a `note`.
+ *
+ * The new cap is in force immediately — no restart — but LOWERING IT CANCELS NOTHING. Jobs already
+ * running run to completion; the cap applies to the next job that starts. A script that drops the
+ * cap to 1 has not stopped the four jobs in flight.
+ */
+export type SettingWritten = SettingRow & {
+    stored: true;
+    note?: string;
+};
 export type SsoClaimMap = {
     subject: string;
     username: string;
@@ -406,9 +450,15 @@ export type SsoConfig = {
      */
     requiredGroups: string[];
     /**
-     * The role an account this provider MINTS is created at. Deliberately not narrowed to `Role`: the
-     * server stores this string without validating it, and one it does not recognise ranks below
-     * viewer. Whatever it says is the floor every person who signs in through this provider gets.
+     * The role an account this provider MINTS is created at, and **empty means INHERIT** — the host's
+     * `default_role` setting, resolved when the account is provisioned rather than frozen when the
+     * provider was saved. Inherit falls back to `viewer` when the host default is unset, and never to
+     * admin by omission.
+     *
+     * Deliberately not narrowed to `Role`: the server stores this string without validating it, and
+     * one it does not recognise ranks below viewer. A provider stored before 0.33.0 carries a literal
+     * `"viewer"` (the server used to fill an empty value in), and keeps it until it is saved again
+     * with `''`.
      */
     defaultRole: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samyx/preview-stacks-client",
-  "version": "0.32.0",
+  "version": "0.33.1",
   "description": "Typed API client for a pstack control plane: deployments, jobs, readiness, containers, logs, notifiers.",
   "repository": {
     "type": "git",