@deveye/types 0.20.1 → 0.20.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,15 +5,14 @@ import {
5
5
  sha256HexSchema,
6
6
  SYNC_CHUNK_MAX,
7
7
  SYNC_INDEX_BATCH_MAX,
8
- SYNC_PATTERN_MAX,
9
8
  SYNC_REL_PATH_MAX,
10
9
  SYNC_STORAGE_PATH_MAX,
11
10
  syncEntryKindSchema,
12
- syncExclusionKindSchema,
13
11
  syncIndexFingerprintSchema,
14
12
  syncScanModeSchema,
15
13
  syncShareStatusSchema
16
14
  } from '../domain/syncProtocol';
15
+ import { pathExclusionSchema } from '../domain/pathExclusions';
17
16
  import {
18
17
  fileListingSchema,
19
18
  fileMatchSchema,
@@ -301,6 +300,51 @@ export const agentFilesChunkPayloadSchema = z.object({
301
300
  error: z.string().max(500).optional()
302
301
  });
303
302
 
303
+ /** Agent → server: one piece of a folder archive (`data` base64). Consumes one credit. */
304
+ export const AGENT_FILES_ARCHIVE_CHUNK = 'files.archiveChunk' as const;
305
+ export const agentFilesArchiveChunkPayloadSchema = z.object({
306
+ deviceId: z.uuid(),
307
+ opId: z.string().max(64),
308
+ /** 0, 1, 2… : a gap or a repeat fails the archive, frames are never reordered. */
309
+ seq: z.number().int().nonnegative(),
310
+ data: z.string().max(1_400_000)
311
+ });
312
+ export type AgentFilesArchiveChunkPayload = z.infer<typeof agentFilesArchiveChunkPayloadSchema>;
313
+
314
+ /**
315
+ * Agent → server: a sign of life while the archive has nothing to send yet
316
+ * (compression can take long to fill a piece). Consumes no credit.
317
+ */
318
+ export const AGENT_FILES_ARCHIVE_PROGRESS = 'files.archiveProgress' as const;
319
+ export const agentFilesArchiveProgressPayloadSchema = z.object({
320
+ deviceId: z.uuid(),
321
+ opId: z.string().max(64),
322
+ entries: z.number().int().nonnegative(),
323
+ bytesRead: z.number().int().nonnegative()
324
+ });
325
+ export type AgentFilesArchiveProgressPayload = z.infer<
326
+ typeof agentFilesArchiveProgressPayloadSchema
327
+ >;
328
+
329
+ /** Agent → server: how a folder archive ended. The last frame of the operation. */
330
+ export const AGENT_FILES_ARCHIVE_END = 'files.archiveEnd' as const;
331
+ export const agentFilesArchiveEndPayloadSchema = z.object({
332
+ deviceId: z.uuid(),
333
+ opId: z.string().max(64),
334
+ ok: z.boolean(),
335
+ error: z.string().max(500).optional(),
336
+ files: z.number().int().nonnegative(),
337
+ dirs: z.number().int().nonnegative(),
338
+ bytesRead: z.number().int().nonnegative(),
339
+ /** Entries left out because they could not be read. */
340
+ skipped: z.number().int().nonnegative(),
341
+ /** Files whose size changed while they were read: archived padded or cut. */
342
+ changed: z.number().int().nonnegative(),
343
+ /** The first skipped or changed entries, and why. */
344
+ samples: z.array(z.object({ path: z.string().max(1024), reason: z.string().max(120) })).max(20)
345
+ });
346
+ export type AgentFilesArchiveEndPayload = z.infer<typeof agentFilesArchiveEndPayloadSchema>;
347
+
304
348
  const syncOpId = z.string().min(1).max(64);
305
349
  const syncRelPath = z.string().min(1).max(SYNC_REL_PATH_MAX);
306
350
 
@@ -543,6 +587,18 @@ export const agentClientMessageSchema = z.discriminatedUnion('command', [
543
587
  command: z.literal(AGENT_FILES_CHUNK),
544
588
  payload: agentFilesChunkPayloadSchema
545
589
  }),
590
+ z.object({
591
+ command: z.literal(AGENT_FILES_ARCHIVE_CHUNK),
592
+ payload: agentFilesArchiveChunkPayloadSchema
593
+ }),
594
+ z.object({
595
+ command: z.literal(AGENT_FILES_ARCHIVE_PROGRESS),
596
+ payload: agentFilesArchiveProgressPayloadSchema
597
+ }),
598
+ z.object({
599
+ command: z.literal(AGENT_FILES_ARCHIVE_END),
600
+ payload: agentFilesArchiveEndPayloadSchema
601
+ }),
546
602
  z.object({
547
603
  command: z.literal(AGENT_SYNC_CHANGED),
548
604
  payload: agentSyncChangedPayloadSchema
@@ -768,6 +824,39 @@ export const agentFilesUploadPayloadSchema = z.object({
768
824
  });
769
825
  export type AgentFilesUploadPayload = z.infer<typeof agentFilesUploadPayloadSchema>;
770
826
 
827
+ /**
828
+ * Archive a folder as a `.tar.gz` built on the machine, streamed as
829
+ * `files.archiveChunk` frames, each spending one credit. The agent sends no
830
+ * more than the credits the server grants: memory on both sides stays bounded
831
+ * whatever the folder's size, and a slow destination slows the machine down.
832
+ */
833
+ export const AGENT_FILES_ARCHIVE = 'files.archive' as const;
834
+ /** What an agent that knows `files.archive` declares in `report.agent.probes`. */
835
+ export const AGENT_FOLDER_ARCHIVE_PROBE = 'folderArchive';
836
+ export const agentFilesArchivePayloadSchema = z.object({
837
+ opId: filesOpId,
838
+ path: filesPath,
839
+ exclusions: z.array(pathExclusionSchema).max(200),
840
+ /** Do not descend into another filesystem (a network mount, a removable disk). */
841
+ oneFileSystem: z.boolean(),
842
+ /** Credits granted up front. */
843
+ window: z.number().int().min(1).max(64)
844
+ });
845
+ export type AgentFilesArchivePayload = z.infer<typeof agentFilesArchivePayloadSchema>;
846
+
847
+ /** More credits for a folder archive, as the server consumes its pieces. */
848
+ export const AGENT_FILES_ARCHIVE_CREDIT = 'files.archiveCredit' as const;
849
+ export const agentFilesArchiveCreditPayloadSchema = z.object({
850
+ opId: filesOpId,
851
+ credits: z.number().int().min(1).max(64)
852
+ });
853
+ export type AgentFilesArchiveCreditPayload = z.infer<typeof agentFilesArchiveCreditPayloadSchema>;
854
+
855
+ /** Stop a folder archive: the agent ends it with `files.archiveEnd` and an error. */
856
+ export const AGENT_FILES_ARCHIVE_CANCEL = 'files.archiveCancel' as const;
857
+ export const agentFilesArchiveCancelPayloadSchema = z.object({ opId: filesOpId });
858
+ export type AgentFilesArchiveCancelPayload = z.infer<typeof agentFilesArchiveCancelPayloadSchema>;
859
+
771
860
  /**
772
861
  * CloudSync, serveur → agent. Le serveur orchestre tout : l'agent reçoit ses
773
862
  * assignations (`sync.config`), scanne sur ordre, transfère sur ordre.
@@ -779,12 +868,7 @@ export const syncShareAssignmentSchema = z.object({
779
868
  localPath: z.string().min(1).max(SYNC_STORAGE_PATH_MAX),
780
869
  /** `paused` = watcher coupé, scans refusés (pause partage OU appareil). */
781
870
  status: syncShareStatusSchema,
782
- exclusions: z.array(
783
- z.object({
784
- kind: syncExclusionKindSchema,
785
- pattern: z.string().min(1).max(SYNC_PATTERN_MAX)
786
- })
787
- ),
871
+ exclusions: z.array(pathExclusionSchema),
788
872
  /**
789
873
  * Plafond de débit des MONTÉES, en octets/s ; `null` = illimité. Le
790
874
  * limiteur vit chez l'émetteur : l'agent pour les montées, le serveur pour
@@ -1092,6 +1176,18 @@ export const agentServerMessageSchema = z.discriminatedUnion('command', [
1092
1176
  command: z.literal(AGENT_FILES_UPLOAD),
1093
1177
  payload: agentFilesUploadPayloadSchema
1094
1178
  }),
1179
+ z.object({
1180
+ command: z.literal(AGENT_FILES_ARCHIVE),
1181
+ payload: agentFilesArchivePayloadSchema
1182
+ }),
1183
+ z.object({
1184
+ command: z.literal(AGENT_FILES_ARCHIVE_CREDIT),
1185
+ payload: agentFilesArchiveCreditPayloadSchema
1186
+ }),
1187
+ z.object({
1188
+ command: z.literal(AGENT_FILES_ARCHIVE_CANCEL),
1189
+ payload: agentFilesArchiveCancelPayloadSchema
1190
+ }),
1095
1191
  z.object({
1096
1192
  command: z.literal(AGENT_SYNC_CONFIG),
1097
1193
  payload: agentSyncConfigPayloadSchema
@@ -1137,7 +1233,8 @@ export type OrderSignature = z.infer<typeof orderSignatureSchema>;
1137
1233
  /**
1138
1234
  * The orders the server signs (`ORDER_SIGNING_KEY`) and the agent refuses
1139
1235
  * unsigned: what runs code, writes or deletes files, changes the agent's
1140
- * privileges or its life. Mirror of `SIGNED_COMMANDS` in `agent/src/protocol.rs`.
1236
+ * privileges or its life, or drives its containers. Mirror of
1237
+ * `SIGNED_COMMANDS` in `agent/src/protocol.rs`.
1141
1238
  */
1142
1239
  export const SIGNED_AGENT_COMMANDS: ReadonlySet<string> = new Set([
1143
1240
  AGENT_TERM_OPEN,
@@ -1147,7 +1244,8 @@ export const SIGNED_AGENT_COMMANDS: ReadonlySet<string> = new Set([
1147
1244
  AGENT_POWER,
1148
1245
  AGENT_DESTROY,
1149
1246
  AGENT_PKG_UPGRADE,
1150
- AGENT_LIFECYCLE
1247
+ AGENT_LIFECYCLE,
1248
+ AGENT_DOCKER_ACTION
1151
1249
  ]);
1152
1250
 
1153
1251
  /**
@@ -28,10 +28,17 @@ declare module 'deveye-sdk-client' {
28
28
  FeatureDomain,
29
29
  FeatureId,
30
30
  MinimalUser,
31
+ PathExclusionKind,
31
32
  User,
32
33
  WorkspaceCapability
33
34
  } from '@deveye/types';
34
- import type { AccountPlan, FeatureManifest, ManifestCommand } from '@deveye/types/sdk';
35
+ import type {
36
+ AccountPlan,
37
+ FeatureManifest,
38
+ ManifestCommand,
39
+ PageTheme,
40
+ PageThemeChoice
41
+ } from '@deveye/types/sdk';
35
42
  import type { SdkDeviceSummary } from '@deveye/types/sdk/client';
36
43
 
37
44
  // ── UI kit ─────────────────────────────────────────────────────────────
@@ -85,17 +92,25 @@ declare module 'deveye-sdk-client' {
85
92
  'aria-label'?: string;
86
93
  className?: string;
87
94
  }>;
88
- /** One choice of a `SearchSelect`. `prefix` is decorative (a flag, an avatar); `keywords` widen what the search reads. */
95
+ /**
96
+ * One choice of a `SearchSelect`. `prefix` is decorative (a flag, an avatar);
97
+ * `keywords` widen what the search reads. Options sharing a `group` are
98
+ * listed together under that heading, groups in order of first appearance.
99
+ * A `disabled` option is shown but cannot be picked: say why in `detail`.
100
+ */
89
101
  export interface SearchSelectOption<T extends string = string> {
90
102
  value: T;
91
103
  label: string;
92
104
  prefix?: ReactNode;
93
105
  detail?: string;
94
106
  keywords?: readonly string[];
107
+ group?: string;
108
+ disabled?: boolean;
95
109
  }
96
110
  /**
97
- * A dropdown one can search in (accent- and case-insensitive), for a list too
98
- * long to scan: currencies, units, countries. Under ten choices or so,
111
+ * A dropdown one can search in (accent- and case-insensitive, group names
112
+ * included), for a list too long to scan or sorted into groups:
113
+ * currencies, units, countries. Under ten ungrouped choices or so,
99
114
  * `SelectInput` stays simpler. Safe inside a Dialog: the panel is portaled.
100
115
  */
101
116
  export function SearchSelect<T extends string>(props: {
@@ -347,17 +362,29 @@ declare module 'deveye-sdk-client' {
347
362
  hint: string;
348
363
  /** A key is on file for this provider. */
349
364
  held: boolean;
350
- /** `false` for a provider that needs none (Open-Meteo): shown, nothing to set. */
351
- needsKey?: boolean;
365
+ /**
366
+ * Whether a key is wanted. `false` for a provider that needs none
367
+ * (Open-Meteo): shown, nothing to set. `'optional'` when the row works
368
+ * without one and a key only enriches it. Required by default.
369
+ */
370
+ needsKey?: boolean | 'optional';
352
371
  /** Where to get one. Only offered while no key is held. */
353
372
  signupUrl?: string;
354
373
  /** Icon class suffix, without the `icon-` prefix. */
355
374
  icon?: string;
375
+ /** Who issues the key, when the row bears another name. Defaults to `label`. */
376
+ issuer?: string;
377
+ /** What the key changes, heading the dialog. Defaults to `hint`. */
378
+ keyHint?: string;
379
+ /** Pills after the name: a price tier, a scope. */
380
+ badges?: { label: string; tone?: 'neutral' | 'accent' | 'warning' }[];
381
+ /** Consecutive rows of the same group share a heading. */
382
+ group?: string;
356
383
  }
357
384
  /**
358
- * The `sources` tab of a feature whose providers are a fixed list, each
359
- * wanting one key. Renders the rows, the add/edit button on each, and the
360
- * dialog. `onSave` / `onRemove` reject to keep the dialog open on the error.
385
+ * A fixed list of providers, each wanting one key (or none): the rows, the
386
+ * add/edit button on each, and the dialog. `onSave` / `onRemove` reject to
387
+ * keep the dialog open on the error.
361
388
  */
362
389
  export const ProviderKeys: ComponentType<{
363
390
  rows: ProviderKeyRow[];
@@ -563,6 +590,49 @@ declare module 'deveye-sdk-client' {
563
590
  onPick: (path: string) => void;
564
591
  /** What the folder is for, said by the caller. */
565
592
  description?: string;
593
+ /** Offer to create a folder; false to pick what exists (what gets backed up). Default true. */
594
+ allowCreate?: boolean;
595
+ }>;
596
+ /**
597
+ * A path on a device: typed (a known path, an offline device) or picked by
598
+ * browsing its folders. The label stays the caller's, outside a `<label>`
599
+ * that would wrap the button: pass `id` for a `<label htmlFor>`, or
600
+ * `aria-label`. `action` is one more button at the end of the row.
601
+ */
602
+ export const DeviceFolderField: ComponentType<{
603
+ /** The device to browse; without it, "Parcourir" stays disabled. */
604
+ device: { id: string; name: string } | null;
605
+ value: string;
606
+ onChange: (path: string) => void;
607
+ placeholder?: string;
608
+ id?: string;
609
+ 'aria-label'?: string;
610
+ pickerDescription?: string;
611
+ allowCreate?: boolean;
612
+ disabled?: boolean;
613
+ action?: ReactNode;
614
+ }>;
615
+ /** One rule of a `PathExclusionsEditor`. */
616
+ export interface PathExclusionItem {
617
+ key: string | number;
618
+ kind: PathExclusionKind;
619
+ pattern: string;
620
+ }
621
+ /**
622
+ * The exclusions of a walked folder (a CloudSync share, a backed-up
623
+ * folder): exact path, component name or regex, relative to its root,
624
+ * validated the way the agent will run them. `onAdd` gets a rule already
625
+ * validated; `false` or a rejection keeps what was typed (say why where
626
+ * you show your errors). `scope` ends the suggestions' tooltip ("le
627
+ * partage", "le dossier").
628
+ */
629
+ export const PathExclusionsEditor: ComponentType<{
630
+ items: readonly PathExclusionItem[];
631
+ onAdd: (kind: PathExclusionKind, pattern: string) => boolean | Promise<boolean>;
632
+ onRemove: (key: string | number) => void;
633
+ canWrite: boolean;
634
+ scope: string;
635
+ disabled?: boolean;
566
636
  }>;
567
637
  /**
568
638
  * The workspace's enrolled devices, live: what the Devices module offers
@@ -627,6 +697,38 @@ declare module 'deveye-sdk-client' {
627
697
  * has no plan provider (everything unlimited): never read it as "free".
628
698
  */
629
699
  export function useAccountPlan(): AccountPlan | null;
700
+ /**
701
+ * How many of the account's items its plan holds paused, by
702
+ * `<featureId>.<quotaKey>`, only the keys that have some. Empty while
703
+ * loading and without a plan provider.
704
+ */
705
+ export function usePlanPauses(): Readonly<Record<string, number>>;
706
+ /** The badge of an item its owner's plan holds paused (a `stock` quota). */
707
+ export const PlanPausedBadge: ComponentType<{ className?: string }>;
708
+ /**
709
+ * The notice above a list that holds items paused by the plan: how many,
710
+ * why, what still runs, and for the workspace owner the way to the plans.
711
+ * Renders nothing at 0. `one` and `many` name the item: "service
712
+ * surveillé", "services surveillés".
713
+ */
714
+ export const PlanPausedNotice: ComponentType<{ count: number; one: string; many: string }>;
715
+ /**
716
+ * The look of a public page your module serves: its theme (`themes`, in
717
+ * that order; `auto` follows the visitor) and its accent (an account
718
+ * colour's name, a `#rrggbb`, or `''` for `ownAccent`, the page's own).
719
+ * `preview` renders under the fields: a miniature of your page in that
720
+ * look. Pair it with `pageAccentSchema` and `resolvePageAccent` from
721
+ * `@deveye/types/sdk`.
722
+ */
723
+ export function PageLookFields<T extends PageThemeChoice>(props: {
724
+ theme: T;
725
+ accent: string;
726
+ themes: readonly T[];
727
+ ownAccent: Readonly<Record<PageTheme, string>>;
728
+ disabled?: boolean;
729
+ onChange: (next: { theme: T; accent: string }) => void;
730
+ preview?: ReactNode;
731
+ }): ReactNode;
630
732
  /** Opens an account view (`manifest.accountEntry`): the given module's, or the first one. No-op without any. */
631
733
  export function openAccountView(featureId?: string): void;
632
734
  export interface LiveOutlineProps {
@@ -694,11 +796,17 @@ declare module 'deveye-sdk-client' {
694
796
  * The client contract another module offers (`FeatureClient.providers`,
695
797
  * keys in `@deveye/types/sdk`): how a module composes another's screens
696
798
  * (Projects renders the linked items of Git, Uptime...). `undefined` when
697
- * that module is not installed: degrade, never assume.
799
+ * that module is not installed: degrade, never assume. A feature in preview
800
+ * the current account does not see offers nothing either.
698
801
  */
699
802
  export function moduleClientProvider<T>(key: string): T | undefined;
700
803
  /** The signed-in user, `null` before the session answers. */
701
804
  export function useCurrentUser(): User | null;
805
+ /**
806
+ * The features in preview the current account does not see (it is not an
807
+ * administrator): no tile, no link, no row that names them.
808
+ */
809
+ export function useHiddenFeatures(): ReadonlySet<string>;
702
810
  /** Image inputs accepted by `fileToSquareDataUrl`. */
703
811
  export const ACCEPTED_TYPES: readonly string[];
704
812
  export const MAX_INPUT_BYTES: number;
package/src/sdk/client.ts CHANGED
@@ -150,6 +150,8 @@ export interface UptimeLinkedService {
150
150
  name: string;
151
151
  url: string;
152
152
  enabled: boolean;
153
+ /** Its owner's plan holds it paused: nothing is measured until the limit rises. */
154
+ planPaused: boolean;
153
155
  /** Projected here from another workspace. */
154
156
  foreign?: boolean;
155
157
  status: string;
@@ -297,7 +299,7 @@ export interface DeployLinkedCandidate {
297
299
  name: string;
298
300
  /** Projected here from another workspace. */
299
301
  foreign?: boolean;
300
- /** The instance host, as the module labels it (« dokploy.example.com »). */
302
+ /** Where the target lives, as the module labels it (« dokploy.example.com », « github.com/owner/repo »). */
301
303
  host: string;
302
304
  }
303
305
 
@@ -416,6 +418,22 @@ export interface AudienceClientProvider {
416
418
  }>;
417
419
  }
418
420
 
421
+ /**
422
+ * What the Invoicing module offers other screens under
423
+ * `INVOICING_CLIENT_PROVIDER`. It sends Invoicing's own command under the
424
+ * caller's session: the same rights, audit and "invoice settled" notice as a
425
+ * payment typed in Invoicing.
426
+ */
427
+ export interface InvoicingClientProvider {
428
+ /** Records a bank transfer received on this invoice. Rejects as the command does (rights, overpayment). */
429
+ recordPayment(input: {
430
+ docId: number;
431
+ paidOn: string;
432
+ amountCents: number;
433
+ reference: string;
434
+ }): Promise<void>;
435
+ }
436
+
419
437
  /**
420
438
  * What the Mail module offers the host's screens under `MAIL_CLIENT_PROVIDER`:
421
439
  * the ready senders (open tier, enabled) an email notification channel picks
@@ -0,0 +1,150 @@
1
+ import assert from 'node:assert/strict';
2
+ import test from 'node:test';
3
+
4
+ import { defineModuleEnv, moduleEnvProblem, readModuleEnv } from './env';
5
+
6
+ const SPEC = defineModuleEnv({
7
+ X_TICK_SECONDS: { kind: 'int', default: 60 },
8
+ X_PORT: { kind: 'int', default: 2525, min: 0 },
9
+ X_NAME: { kind: 'text', default: 'eur' },
10
+ X_DIR: { kind: 'path', default: '/data/x' },
11
+ X_SITE_URL: { kind: 'url', default: 'https://deveye.fr' },
12
+ X_IPV4_ONLY: { kind: 'flag', default: true },
13
+ X_DIRECTORY: { kind: 'choice', default: 'production', choices: ['production', 'staging'] },
14
+ X_SECRET: { kind: 'secret' },
15
+ X_CLIENT_ID: { kind: 'text', default: '', optional: true }
16
+ });
17
+
18
+ test('readModuleEnv: an empty environment gets every default, and names each one', () => {
19
+ const { values, defaulted } = readModuleEnv(SPEC, {});
20
+ assert.deepEqual(values, {
21
+ X_TICK_SECONDS: 60,
22
+ X_PORT: 2525,
23
+ X_NAME: 'eur',
24
+ X_DIR: '/data/x',
25
+ X_SITE_URL: 'https://deveye.fr',
26
+ X_IPV4_ONLY: true,
27
+ X_DIRECTORY: 'production',
28
+ X_SECRET: '',
29
+ X_CLIENT_ID: ''
30
+ });
31
+ // An optional variable left unset is an option the install does not use: no word.
32
+ assert.deepEqual(
33
+ defaulted.map((d) => d.name),
34
+ [
35
+ 'X_TICK_SECONDS',
36
+ 'X_PORT',
37
+ 'X_NAME',
38
+ 'X_DIR',
39
+ 'X_SITE_URL',
40
+ 'X_IPV4_ONLY',
41
+ 'X_DIRECTORY',
42
+ 'X_SECRET'
43
+ ]
44
+ );
45
+ assert.ok(defaulted.every((d) => d.reason === 'unset'));
46
+ assert.deepEqual(
47
+ defaulted.find((d) => d.name === 'X_SITE_URL'),
48
+ { name: 'X_SITE_URL', reason: 'unset', value: 'https://deveye.fr' }
49
+ );
50
+ });
51
+
52
+ test('readModuleEnv: explicit values are read and trimmed, and nothing is reported', () => {
53
+ const { values, defaulted } = readModuleEnv(SPEC, {
54
+ X_TICK_SECONDS: ' 30 ',
55
+ X_PORT: '0',
56
+ X_NAME: 'usd',
57
+ X_DIR: '/srv/x',
58
+ X_SITE_URL: 'https://exemple.fr',
59
+ X_IPV4_ONLY: 'FALSE',
60
+ X_DIRECTORY: 'staging',
61
+ X_SECRET: 's3cr3t',
62
+ X_CLIENT_ID: 'abc'
63
+ });
64
+ assert.equal(values.X_TICK_SECONDS, 30);
65
+ assert.equal(values.X_PORT, 0);
66
+ assert.equal(values.X_NAME, 'usd');
67
+ assert.equal(values.X_DIR, '/srv/x');
68
+ assert.equal(values.X_SITE_URL, 'https://exemple.fr');
69
+ assert.equal(values.X_IPV4_ONLY, false);
70
+ assert.equal(values.X_DIRECTORY, 'staging');
71
+ assert.equal(values.X_SECRET, 's3cr3t');
72
+ assert.equal(values.X_CLIENT_ID, 'abc');
73
+ assert.deepEqual(defaulted, []);
74
+ });
75
+
76
+ test('readModuleEnv: an empty string is explicit, falls back quietly, and means "none" for an address', () => {
77
+ const blanks = Object.fromEntries(Object.keys(SPEC).map((name) => [name, '']));
78
+ const { values, defaulted } = readModuleEnv(SPEC, blanks);
79
+ assert.equal(values.X_TICK_SECONDS, 60);
80
+ assert.equal(values.X_DIR, '/data/x');
81
+ assert.equal(values.X_NAME, 'eur');
82
+ assert.equal(values.X_IPV4_ONLY, true);
83
+ assert.equal(values.X_DIRECTORY, 'production');
84
+ assert.equal(values.X_SITE_URL, '');
85
+ assert.equal(values.X_SECRET, '');
86
+ assert.deepEqual(defaulted, []);
87
+ });
88
+
89
+ test('readModuleEnv: an unreadable value falls back and is reported as invalid', () => {
90
+ const { values, defaulted } = readModuleEnv(SPEC, {
91
+ X_TICK_SECONDS: '0',
92
+ X_PORT: '-1',
93
+ X_SITE_URL: 'deveye.fr',
94
+ X_IPV4_ONLY: 'oui',
95
+ X_DIRECTORY: 'test'
96
+ });
97
+ assert.equal(values.X_TICK_SECONDS, 60);
98
+ assert.equal(values.X_PORT, 2525);
99
+ assert.equal(values.X_SITE_URL, 'https://deveye.fr');
100
+ assert.equal(values.X_IPV4_ONLY, true);
101
+ assert.equal(values.X_DIRECTORY, 'production');
102
+ const invalid = defaulted.filter((d) => d.reason === 'invalid').map((d) => d.name);
103
+ assert.deepEqual(invalid, [
104
+ 'X_TICK_SECONDS',
105
+ 'X_PORT',
106
+ 'X_SITE_URL',
107
+ 'X_IPV4_ONLY',
108
+ 'X_DIRECTORY'
109
+ ]);
110
+ });
111
+
112
+ test('readModuleEnv: an integer must be whole and at least its minimum', () => {
113
+ const spec = defineModuleEnv({ X_RATIO: { kind: 'int', default: 30, min: 2 } });
114
+ assert.equal(readModuleEnv(spec, { X_RATIO: '2' }).values.X_RATIO, 2);
115
+ assert.equal(readModuleEnv(spec, { X_RATIO: '1' }).values.X_RATIO, 30);
116
+ assert.equal(readModuleEnv(spec, { X_RATIO: '2.5' }).values.X_RATIO, 30);
117
+ assert.equal(readModuleEnv(spec, { X_RATIO: 'abc' }).values.X_RATIO, 30);
118
+ });
119
+
120
+ test('readModuleEnv: an invalid optional value is still reported', () => {
121
+ const spec = defineModuleEnv({ X_HOOK: { kind: 'url', default: '', optional: true } });
122
+ assert.deepEqual(readModuleEnv(spec, {}).defaulted, []);
123
+ assert.deepEqual(readModuleEnv(spec, { X_HOOK: 'ftp://x' }).defaulted, [
124
+ { name: 'X_HOOK', reason: 'invalid', value: '' }
125
+ ]);
126
+ });
127
+
128
+ test('readModuleEnv: the values stay writable, for tests that redirect a directory', () => {
129
+ const { values } = readModuleEnv(SPEC, {});
130
+ values.X_DIR = '/tmp/scratch';
131
+ assert.equal(values.X_DIR, '/tmp/scratch');
132
+ });
133
+
134
+ test('moduleEnvProblem: refuses what the host could not read', () => {
135
+ assert.equal(moduleEnvProblem(SPEC), null);
136
+ assert.match(
137
+ moduleEnvProblem({ 'x-tick': { kind: 'int', default: 1 } }) ?? '',
138
+ /not an environment variable name/
139
+ );
140
+ assert.match(
141
+ moduleEnvProblem({ X_TICK: { kind: 'number', default: 1 } }) ?? '',
142
+ /unknown kind/
143
+ );
144
+ assert.match(moduleEnvProblem({ X_TICK: null }) ?? '', /unknown kind/);
145
+ assert.match(
146
+ moduleEnvProblem({ X_MODE: { kind: 'choice', default: 'c', choices: ['a', 'b'] } }) ?? '',
147
+ /not one of the choices/
148
+ );
149
+ assert.match(moduleEnvProblem(null) ?? '', /not an object/);
150
+ });