@orkestrel/scaffold 0.0.114 → 0.0.116

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.
Files changed (108) hide show
  1. package/dist/bin/main.js +137 -15
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/orchestration.md +5 -3
  4. package/dist/host/agents/platforms/windows.md +1 -0
  5. package/dist/host/agents/skills/orkestrel-align/references/integration.md +1 -1
  6. package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +4 -4
  7. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -1
  8. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +8 -2
  9. package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +1 -0
  10. package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +1 -1
  11. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
  12. package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +1 -0
  13. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +9 -3
  14. package/dist/host/claude/agents/analyst.md +1 -1
  15. package/dist/host/claude/agents/astra.md +2 -2
  16. package/dist/host/claude/agents/builder.md +4 -4
  17. package/dist/host/claude/agents/opus.md +3 -3
  18. package/dist/host/claude/agents/orkestrel.md +5 -7
  19. package/dist/host/claude/agents/planner.md +8 -2
  20. package/dist/host/claude/rules/campaign.md +2 -1
  21. package/dist/host/claude/rules/documentation.md +1 -0
  22. package/dist/host/claude/rules/names.md +3 -1
  23. package/dist/host/claude/rules/tests.md +7 -4
  24. package/dist/host/claude/rules/writing.md +1 -0
  25. package/dist/host/claude/skills/enterprise-bootstrap/SKILL.md +1 -2
  26. package/dist/host/claude/skills/orkestrel-align/SKILL.md +1 -1
  27. package/dist/host/claude/skills/orkestrel-build/SKILL.md +1 -2
  28. package/dist/host/claude/skills/orkestrel-debrief/SKILL.md +1 -2
  29. package/dist/host/claude/skills/orkestrel-dispatch/SKILL.md +1 -1
  30. package/dist/host/claude/skills/orkestrel-falsify/SKILL.md +1 -1
  31. package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
  32. package/dist/host/claude/skills/orkestrel-journey/SKILL.md +1 -1
  33. package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
  34. package/dist/host/claude/skills/orkestrel-polish/SKILL.md +1 -2
  35. package/dist/host/claude/skills/orkestrel-publish/SKILL.md +1 -2
  36. package/dist/host/claude/skills/orkestrel-scout/SKILL.md +1 -1
  37. package/dist/host/codex/agents/analyst.toml +8 -5
  38. package/dist/host/codex/agents/astra.toml +4 -5
  39. package/dist/host/codex/agents/builder.toml +5 -5
  40. package/dist/host/codex/agents/opus.toml +3 -4
  41. package/dist/host/codex/agents/orkestrel.toml +2 -1
  42. package/dist/host/codex/agents/planner.toml +8 -5
  43. package/dist/host/codex/agents/reviewer.toml +5 -4
  44. package/dist/host/guides/abort.md +17 -17
  45. package/dist/host/guides/agent.md +445 -445
  46. package/dist/host/guides/brief.md +143 -143
  47. package/dist/host/guides/browser.md +731 -731
  48. package/dist/host/guides/budget.md +39 -39
  49. package/dist/host/guides/capture.md +298 -298
  50. package/dist/host/guides/console.md +109 -109
  51. package/dist/host/guides/contract.md +335 -335
  52. package/dist/host/guides/csv.md +30 -30
  53. package/dist/host/guides/database.md +163 -163
  54. package/dist/host/guides/emitter.md +17 -17
  55. package/dist/host/guides/form.md +99 -99
  56. package/dist/host/guides/guide.md +361 -183
  57. package/dist/host/guides/html.md +49 -49
  58. package/dist/host/guides/indexeddb.md +40 -40
  59. package/dist/host/guides/interpret.md +139 -139
  60. package/dist/host/guides/lsp.md +114 -114
  61. package/dist/host/guides/markdown.md +68 -68
  62. package/dist/host/guides/mcp.md +3745 -3745
  63. package/dist/host/guides/middleware.md +170 -170
  64. package/dist/host/guides/msg.md +95 -95
  65. package/dist/host/guides/ndjson.md +8 -8
  66. package/dist/host/guides/ollama.md +56 -56
  67. package/dist/host/guides/pool.md +21 -21
  68. package/dist/host/guides/probe.md +82 -82
  69. package/dist/host/guides/process.md +99 -99
  70. package/dist/host/guides/program.md +98 -96
  71. package/dist/host/guides/qualifier.md +70 -70
  72. package/dist/host/guides/queue.md +37 -37
  73. package/dist/host/guides/rater.md +38 -38
  74. package/dist/host/guides/reason.md +308 -308
  75. package/dist/host/guides/relation.md +50 -50
  76. package/dist/host/guides/router.md +58 -58
  77. package/dist/host/guides/scaffold.md +554 -419
  78. package/dist/host/guides/sea.md +128 -128
  79. package/dist/host/guides/server.md +100 -100
  80. package/dist/host/guides/sqlite.md +28 -28
  81. package/dist/host/guides/sse.md +20 -20
  82. package/dist/host/guides/study.md +444 -444
  83. package/dist/host/guides/table.md +82 -82
  84. package/dist/host/guides/template.md +41 -41
  85. package/dist/host/guides/terminal.md +121 -121
  86. package/dist/host/guides/test.md +273 -273
  87. package/dist/host/guides/timeout.md +18 -18
  88. package/dist/host/guides/tool.md +27 -27
  89. package/dist/host/guides/toolbox.md +166 -166
  90. package/dist/host/guides/websocket.md +54 -54
  91. package/dist/host/guides/worker.md +24 -24
  92. package/dist/host/guides/workflow.md +187 -187
  93. package/dist/host/guides/workspace.md +55 -55
  94. package/dist/host/manifest.json +93 -93
  95. package/dist/host/tests/setupPolicy.ts +5 -3
  96. package/dist/src/core/index.cjs +89 -3
  97. package/dist/src/core/index.cjs.map +1 -1
  98. package/dist/src/core/index.d.cts +229 -144
  99. package/dist/src/core/index.d.ts +229 -144
  100. package/dist/src/core/index.js +87 -4
  101. package/dist/src/core/index.js.map +1 -1
  102. package/dist/src/server/index.cjs +292 -66
  103. package/dist/src/server/index.cjs.map +1 -1
  104. package/dist/src/server/index.d.cts +188 -6
  105. package/dist/src/server/index.d.ts +188 -6
  106. package/dist/src/server/index.js +287 -69
  107. package/dist/src/server/index.js.map +1 -1
  108. package/package.json +4 -3
@@ -50,150 +50,150 @@ On Windows, `SEAOptions.windows.sign` is optional Authenticode signing. When pre
50
50
 
51
51
  ### Classes
52
52
 
53
- | API | Kind | Summary |
54
- | -------------- | ----- | -------------------------------------------------------------------------- |
55
- | `SEA` | class | Runs a Node.js single executable application build to completion. |
56
- | `Injector` | class | Writes a named resource into a PE, ELF, or Mach-O executable in place. |
57
- | `Asset` | class | Holds one named asset's key, bytes, and compression state. |
58
- | `AssetManager` | class | Collects named assets from a SEA blob or from disk and serves them by key. |
53
+ | Name | Kind | Signature | Summary |
54
+ | -------------- | ----- | -------------------------------------------------------------- | -------------------------------------------------------------------------- |
55
+ | `SEA` | class | `new (options: SEAOptions) => SEAInterface` | Runs a Node.js single executable application build to completion. |
56
+ | `Injector` | class | `new (options: InjectorOptions) => InjectorInterface` | Writes a named resource into a PE, ELF, or Mach-O executable in place. |
57
+ | `Asset` | class | `new (input: AssetInput) => AssetInterface` | Holds one named asset's key, bytes, and compression state. |
58
+ | `AssetManager` | class | `new (options?: AssetManagerOptions) => AssetManagerInterface` | Collects named assets from a SEA blob or from disk and serves them by key. |
59
59
 
60
60
  ### Factories
61
61
 
62
- | API | Kind | Summary |
63
- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
64
- | `createSEA` | function | Creates a SEA build orchestrator over the given options and returns it as a `SEAInterface`, the published contract a caller holds instead of the `SEA` class. |
65
- | `createInjector` | function | Creates a resource injector bound to one target executable and returns it as an `InjectorInterface`, with the executable's format already detected from its header. |
66
- | `createAsset` | function | Creates one named asset from a key and a content buffer and returns it as an `AssetInterface`, with `compressed` inferred from the key where the input leaves it unset. |
67
- | `createAssetManager` | function | Creates an asset collection and returns it as an `AssetManagerInterface`, already carrying whatever assets the running SEA blob embeds. |
62
+ | Name | Kind | Signature | Summary |
63
+ | -------------------- | -------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
64
+ | `createSEA` | function | `(options: SEAOptions) => SEAInterface` | Creates a SEA build orchestrator over the given options and returns it as a `SEAInterface`, the published contract a caller holds instead of the `SEA` class. |
65
+ | `createInjector` | function | `(options: InjectorOptions) => InjectorInterface` | Creates a resource injector bound to one target executable and returns it as an `InjectorInterface`, with the executable's format already detected from its header. |
66
+ | `createAsset` | function | `(input: AssetInput) => AssetInterface` | Creates one named asset from a key and a content buffer and returns it as an `AssetInterface`, with `compressed` inferred from the key where the input leaves it unset. |
67
+ | `createAssetManager` | function | `(options?: AssetManagerOptions) => AssetManagerInterface` | Creates an asset collection and returns it as an `AssetManagerInterface`, already carrying whatever assets the running SEA blob embeds. |
68
68
 
69
69
  ### Constants
70
70
 
71
71
  A `Shape` cell holds the constant's declared type.
72
72
 
73
- | API | Kind | Shape | Summary |
74
- | --------------------------------- | ----- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
75
- | `SEA_SENTINEL_FUSE` | const | `string` | Holds the SEA sentinel fuse value embedded in the Node.js binary, `NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2`. |
76
- | `SEA_BLOB_RESOURCE` | const | `string` | Names the SEA blob resource in the executable, `NODE_SEA_BLOB`. |
77
- | `DEFAULT_SEA_COMPRESSION_QUALITY` | const | `number` | Holds the default Brotli compression quality level, 11, the maximum Brotli accepts. |
78
- | `WINDOWS_SUBSYSTEM_GUI` | const | `number` | Holds the Windows PE subsystem value for a GUI application, 2, which launches without a terminal window. |
79
- | `WINDOWS_SUBSYSTEM_CONSOLE` | const | `number` | Holds the Windows PE subsystem value for a console application, 3. |
80
- | `BROTLI_EXTENSION` | const | `string` | Names the file extension indicating Brotli compression, `.br`. |
81
- | `SKIP_EXTENSIONS` | const | `ReadonlySet<string>` | Lists the file extensions Brotli compression skips, the already-compressed archive, image, font, and media formats. |
82
- | `PE_MAGIC` | const | `number` | Holds the DOS MZ header magic, 0x5a4d, the first two bytes of a PE file. |
83
- | `PE_SIGNATURE` | const | `number` | Holds the PE signature, 0x00004550, the bytes `PE\0\0` read as a 32-bit value. |
84
- | `PE32_MAGIC` | const | `number` | Holds the PE32 optional header magic, 0x10b. |
85
- | `PE32_PLUS_MAGIC` | const | `number` | Holds the PE32+ optional header magic, 0x20b, the 64-bit form. |
86
- | `ELF_MAGIC` | const | `number` | Holds the ELF magic, 0x7f454c46, the bytes 0x7F `E` `L` `F` read as a 32-bit big-endian value. |
87
- | `ELF_CLASS_64` | const | `number` | Holds the ELF 64-bit class identifier, 2. |
88
- | `ELF_DATA_LSB` | const | `number` | Holds the ELF little-endian data encoding, 1. |
89
- | `ELF_PT_NOTE` | const | `number` | Holds the ELF program header type for a note segment, 4. |
90
- | `ELF_PT_LOAD` | const | `number` | Holds the ELF program header type for a loadable segment, 1. |
91
- | `ELF_PT_PHDR` | const | `number` | Holds the ELF program header type for the program header table itself, 6. |
92
- | `ELF_PF_R` | const | `number` | Holds the ELF segment permission flag marking a segment readable, 4. |
93
- | `ELF_PAGE_SIZE` | const | `number` | Holds the page size an injected ELF segment is aligned to, 0x1000. |
94
- | `MACHO_MAGIC_64` | const | `number` | Holds the Mach-O 64-bit magic, 0xfeedfacf, in little-endian byte order. |
95
- | `MACHO_LC_SEGMENT_64` | const | `number` | Holds the Mach-O `LC_SEGMENT_64` load command, 0x19. |
96
- | `PE_RT_RCDATA` | const | `number` | Holds the PE resource type `RT_RCDATA` for raw data, 10. |
97
- | `PE_RESOURCE_DIR_SIZE` | const | `number` | Holds the size of `IMAGE_RESOURCE_DIRECTORY` in bytes, 16. |
98
- | `PE_RESOURCE_ENTRY_SIZE` | const | `number` | Holds the size of `IMAGE_RESOURCE_DIRECTORY_ENTRY` in bytes, 8. |
99
- | `PE_RESOURCE_DATA_ENTRY_SIZE` | const | `number` | Holds the size of `IMAGE_RESOURCE_DATA_ENTRY` in bytes, 16. |
100
- | `PE_SECTION_HEADER_SIZE` | const | `number` | Holds the PE section header size in bytes, 40. |
101
- | `PE_RESOURCE_SUBDIR_FLAG` | const | `number` | Holds the high bit mask marking a resource directory entry offset as a subdirectory, 0x80000000. |
102
- | `PE_RESOURCE_NAME_FLAG` | const | `number` | Holds the high bit mask marking a resource entry as named rather than integer-identified, 0x80000000. |
103
- | `PE_SCN_INITIALIZED_DATA` | const | `number` | Marks a section as containing initialized data, 0x00000040. |
104
- | `PE_SCN_MEM_READ` | const | `number` | Marks a section as readable, 0x40000000. |
105
- | `SEA_PLATFORMS` | const | `Readonly<Record<string, SEAPlatform>>` | Holds the platform-specific SEA build configurations, keyed by `process.platform` for `win32`, `darwin`, and `linux`. |
106
- | `SEA_COMPRESSION_MODE_VALUES` | const | `Readonly<Record<SEACompressionMode, number>>` | Maps a `SEACompressionMode` to its numeric Brotli mode value: `generic` to 0, `text` to 1, and `font` to 2. |
107
- | `DEFAULT_ENTRY_FORMAT` | const | `SEAEntryFormat` | Names the default SEA entry point module format when none is specified, `cjs`. |
73
+ | Name | Kind | Signature | Summary |
74
+ | --------------------------------- | ----- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
75
+ | `SEA_SENTINEL_FUSE` | const | `"NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2"` | Holds the SEA sentinel fuse value embedded in the Node.js binary, `NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2`. |
76
+ | `SEA_BLOB_RESOURCE` | const | `"NODE_SEA_BLOB"` | Names the SEA blob resource in the executable, `NODE_SEA_BLOB`. |
77
+ | `DEFAULT_SEA_COMPRESSION_QUALITY` | const | `11` | Holds the default Brotli compression quality level, 11, the maximum Brotli accepts. |
78
+ | `WINDOWS_SUBSYSTEM_GUI` | const | `2` | Holds the Windows PE subsystem value for a GUI application, 2, which launches without a terminal window. |
79
+ | `WINDOWS_SUBSYSTEM_CONSOLE` | const | `3` | Holds the Windows PE subsystem value for a console application, 3. |
80
+ | `BROTLI_EXTENSION` | const | `".br"` | Names the file extension indicating Brotli compression, `.br`. |
81
+ | `SKIP_EXTENSIONS` | const | `ReadonlySet<string>` | Lists the file extensions Brotli compression skips, the already-compressed archive, image, font, and media formats. |
82
+ | `PE_MAGIC` | const | `23117` | Holds the DOS MZ header magic, 0x5a4d, the first two bytes of a PE file. |
83
+ | `PE_SIGNATURE` | const | `17744` | Holds the PE signature, 0x00004550, the bytes `PE\0\0` read as a 32-bit value. |
84
+ | `PE32_MAGIC` | const | `267` | Holds the PE32 optional header magic, 0x10b. |
85
+ | `PE32_PLUS_MAGIC` | const | `523` | Holds the PE32+ optional header magic, 0x20b, the 64-bit form. |
86
+ | `ELF_MAGIC` | const | `2135247942` | Holds the ELF magic, 0x7f454c46, the bytes 0x7F `E` `L` `F` read as a 32-bit big-endian value. |
87
+ | `ELF_CLASS_64` | const | `2` | Holds the ELF 64-bit class identifier, 2. |
88
+ | `ELF_DATA_LSB` | const | `1` | Holds the ELF little-endian data encoding, 1. |
89
+ | `ELF_PT_NOTE` | const | `4` | Holds the ELF program header type for a note segment, 4. |
90
+ | `ELF_PT_LOAD` | const | `1` | Holds the ELF program header type for a loadable segment, 1. |
91
+ | `ELF_PT_PHDR` | const | `6` | Holds the ELF program header type for the program header table itself, 6. |
92
+ | `ELF_PF_R` | const | `4` | Holds the ELF segment permission flag marking a segment readable, 4. |
93
+ | `ELF_PAGE_SIZE` | const | `4096` | Holds the page size an injected ELF segment is aligned to, 0x1000. |
94
+ | `MACHO_MAGIC_64` | const | `4277009103` | Holds the Mach-O 64-bit magic, 0xfeedfacf, in little-endian byte order. |
95
+ | `MACHO_LC_SEGMENT_64` | const | `25` | Holds the Mach-O `LC_SEGMENT_64` load command, 0x19. |
96
+ | `PE_RT_RCDATA` | const | `10` | Holds the PE resource type `RT_RCDATA` for raw data, 10. |
97
+ | `PE_RESOURCE_DIR_SIZE` | const | `16` | Holds the size of `IMAGE_RESOURCE_DIRECTORY` in bytes, 16. |
98
+ | `PE_RESOURCE_ENTRY_SIZE` | const | `8` | Holds the size of `IMAGE_RESOURCE_DIRECTORY_ENTRY` in bytes, 8. |
99
+ | `PE_RESOURCE_DATA_ENTRY_SIZE` | const | `16` | Holds the size of `IMAGE_RESOURCE_DATA_ENTRY` in bytes, 16. |
100
+ | `PE_SECTION_HEADER_SIZE` | const | `40` | Holds the PE section header size in bytes, 40. |
101
+ | `PE_RESOURCE_SUBDIR_FLAG` | const | `2147483648` | Holds the high bit mask marking a resource directory entry offset as a subdirectory, 0x80000000. |
102
+ | `PE_RESOURCE_NAME_FLAG` | const | `2147483648` | Holds the high bit mask marking a resource entry as named rather than integer-identified, 0x80000000. |
103
+ | `PE_SCN_INITIALIZED_DATA` | const | `64` | Marks a section as containing initialized data, 0x00000040. |
104
+ | `PE_SCN_MEM_READ` | const | `1073741824` | Marks a section as readable, 0x40000000. |
105
+ | `SEA_PLATFORMS` | const | `Readonly<Record<string, SEAPlatform>>` | Holds the platform-specific SEA build configurations, keyed by `process.platform` for `win32`, `darwin`, and `linux`. |
106
+ | `SEA_COMPRESSION_MODE_VALUES` | const | `Readonly<Record<SEACompressionMode, number>>` | Maps a `SEACompressionMode` to its numeric Brotli mode value: `generic` to 0, `text` to 1, and `font` to 2. |
107
+ | `DEFAULT_ENTRY_FORMAT` | const | `SEAEntryFormat` | Names the default SEA entry point module format when none is specified, `cjs`. |
108
108
 
109
109
  ### Helpers and errors
110
110
 
111
- | API | Kind | Summary |
112
- | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
113
- | `isExecutableFormat` | function | Checks whether a value is a valid `ExecutableFormat`. |
114
- | `resolvePlatform` | function | Resolves the effective platform configuration. |
115
- | `isPlatformSupported` | function | Checks whether the current or named platform is supported for SEA builds. |
116
- | `ensureExists` | function | Asserts that a path exists, throwing a coded `SEAError` if not. |
117
- | `isCompressible` | function | Checks whether a file's extension is outside `SKIP_EXTENSIONS`, so Brotli compression applies to it. |
118
- | `walkDirectory` | function | Walks a directory recursively and returns every file path it finds, relative to the base and skipping symlinks. |
119
- | `executeShell` | function | Executes a command synchronously and returns stdout. |
120
- | `redactCommand` | function | Redacts password arguments from a shell command, so the command is safe to include in an error message. |
121
- | `computeSize` | function | Computes a size comparison between original and compressed byte counts. |
122
- | `compressFile` | function | Brotli-compresses a single file, writing the output alongside it. |
123
- | `compressDirectory` | function | Compresses all compressible files in a directory tree. |
124
- | `alignTo` | function | Rounds a value up to the next multiple of an alignment boundary. |
125
- | `readPEOffset` | function | Reads the PE header offset from a Windows executable. |
126
- | `readU16` | function | Reads a 16-bit unsigned integer from a file descriptor. |
127
- | `readU32` | function | Reads a 32-bit unsigned little-endian integer from a file descriptor. |
128
- | `readU64` | function | Reads a 64-bit unsigned little-endian integer from a file descriptor. |
129
- | `writeU16` | function | Writes a 16-bit unsigned integer to a file descriptor. |
130
- | `writeU32` | function | Writes a 32-bit unsigned little-endian integer to a file descriptor. |
131
- | `writeU64` | function | Writes a 64-bit unsigned little-endian integer to a file descriptor. |
132
- | `appendFile` | function | Appends a source file to a target file, streaming in fixed-size chunks. |
133
- | `stripTrailingNulls` | function | Truncates a NUL-padded binary name field at its first NUL character. |
134
- | `isPEExecutable` | function | Checks whether a file is a Windows PE executable. |
135
- | `patchPESubsystem` | function | Patches the PE subsystem field in a Windows executable. |
136
- | `stripPESignature` | function | Removes the Authenticode signature from a PE executable by zeroing the security directory entry in the optional header. |
137
- | `buildSignCommand` | function | Builds the `signtool sign` argv for signing a Windows executable. |
138
- | `formatSize` | function | Formats a byte count as a human-readable string. |
139
- | `ensureSafeKey` | function | Asserts that an asset key is safe to use as a relative filesystem/archive key. |
140
- | `ensureContained` | function | Asserts that `path` (resolved against `base`) real-path-resolves to a location inside `base`, defeating a symlink escape. |
141
- | `ensureSafeName` | function | Asserts that `name` is a single safe path segment suitable as an output executable base name. |
142
- | `finalizeExecutable` | function | Finalizes a built executable by durably flushing it to disk and atomically moving it into place. |
143
- | `syncDirectory` | function | Fsyncs a directory to durably persist a prior file rename/create within it. |
144
- | `buildBlobConfig` | function | Builds the Node.js `--experimental-sea-config` JSON object for a SEA blob. |
145
- | `patchSentinelFuse` | function | Patches the sentinel fuse in a binary from `:0` to `:1`. |
146
- | `buildELFNoteHeader` | function | Builds an ELF `PT_NOTE` entry's header bytes (namesz/descsz/type + padded name) for the SEA blob note, without the blob body itself. |
147
- | `alignELFNoteSize` | function | Aligns an ELF note component size to its four-byte boundary. |
148
- | `isPowerOfTwo` | function | Checks whether a number is a nonzero power of two. |
149
- | `copyRange` | function | Copies a byte range from one open file descriptor to another, streaming in fixed-size chunks instead of buffering the whole range in memory. |
150
- | `openBrowser` | function | Launches the system default browser at an http(s) URL. |
151
- | `SEAError` | class | Represents the coded base error for every failure raised by the SEA build. |
152
- | `isSEAError` | function | Checks whether a value is a `SEAError`. |
153
- | `ShellError` | class | Represents an error thrown when a shell command executed through `executeShell` exits non-zero. |
154
- | `isShellError` | function | Checks whether a value is a `ShellError`. |
111
+ | Name | Kind | Signature | Summary |
112
+ | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
113
+ | `isExecutableFormat` | function | `(value: unknown) => value is ExecutableFormat` | Checks whether a value is a valid `ExecutableFormat`. |
114
+ | `resolvePlatform` | function | `(platform?: string) => SEAPlatform \| undefined` | Resolves the effective platform configuration. |
115
+ | `isPlatformSupported` | function | `(platform?: string) => boolean` | Checks whether the current or named platform is supported for SEA builds. |
116
+ | `ensureExists` | function | `(path: string, message: string, code?: SEAErrorCode) => void` | Asserts that a path exists, throwing a coded `SEAError` if not. |
117
+ | `isCompressible` | function | `(path: string) => boolean` | Checks whether a file's extension is outside `SKIP_EXTENSIONS`, so Brotli compression applies to it. |
118
+ | `walkDirectory` | function | `(directory: string, base?: string) => readonly string[]` | Walks a directory recursively and returns every file path it finds, relative to the base and skipping symlinks. |
119
+ | `executeShell` | function | `(command: readonly string[], options?: SEAShellOptions) => Buffer` | Executes a command synchronously and returns stdout. |
120
+ | `redactCommand` | function | `(command: readonly string[]) => readonly string[]` | Redacts password arguments from a shell command, so the command is safe to include in an error message. |
121
+ | `computeSize` | function | `(original: number, compressed: number) => SEACompressionSize` | Computes a size comparison between original and compressed byte counts. |
122
+ | `compressFile` | function | `(input: string, output: string, options?: SEABrotliOptions) => SEACompressionResult` | Brotli-compresses a single file, writing the output alongside it. |
123
+ | `compressDirectory` | function | `(directory: string, options?: SEABrotliOptions, progress?: SEACompressionHandler) => SEACompressionManifest` | Compresses all compressible files in a directory tree. |
124
+ | `alignTo` | function | `(value: number, alignment: number) => number` | Rounds a value up to the next multiple of an alignment boundary. |
125
+ | `readPEOffset` | function | `(fd: number) => number` | Reads the PE header offset from a Windows executable. |
126
+ | `readU16` | function | `(fd: number, offset: number) => number` | Reads a 16-bit unsigned integer from a file descriptor. |
127
+ | `readU32` | function | `(fd: number, offset: number) => number` | Reads a 32-bit unsigned little-endian integer from a file descriptor. |
128
+ | `readU64` | function | `(fd: number, offset: number) => bigint` | Reads a 64-bit unsigned little-endian integer from a file descriptor. |
129
+ | `writeU16` | function | `(fd: number, offset: number, value: number) => void` | Writes a 16-bit unsigned integer to a file descriptor. |
130
+ | `writeU32` | function | `(fd: number, offset: number, value: number) => void` | Writes a 32-bit unsigned little-endian integer to a file descriptor. |
131
+ | `writeU64` | function | `(fd: number, offset: number, value: bigint) => void` | Writes a 64-bit unsigned little-endian integer to a file descriptor. |
132
+ | `appendFile` | function | `(target: string, source: string, chunk?: number) => void` | Appends a source file to a target file, streaming in fixed-size chunks. |
133
+ | `stripTrailingNulls` | function | `(value: string) => string` | Truncates a NUL-padded binary name field at its first NUL character. |
134
+ | `isPEExecutable` | function | `(path: string) => boolean` | Checks whether a file is a Windows PE executable. |
135
+ | `patchPESubsystem` | function | `(path: string, subsystem: number) => void` | Patches the PE subsystem field in a Windows executable. |
136
+ | `stripPESignature` | function | `(path: string) => void` | Removes the Authenticode signature from a PE executable by zeroing the security directory entry in the optional header. |
137
+ | `buildSignCommand` | function | `(sign: SEAWindowsSignOptions, target: string) => readonly string[]` | Builds the `signtool sign` argv for signing a Windows executable. |
138
+ | `formatSize` | function | `(bytes: number) => string` | Formats a byte count as a human-readable string. |
139
+ | `ensureSafeKey` | function | `(key: string) => void` | Asserts that an asset key is safe to use as a relative filesystem/archive key. |
140
+ | `ensureContained` | function | `(base: string, path: string) => string` | Asserts that `path` (resolved against `base`) real-path-resolves to a location inside `base`, defeating a symlink escape. |
141
+ | `ensureSafeName` | function | `(name: string) => void` | Asserts that `name` is a single safe path segment suitable as an output executable base name. |
142
+ | `finalizeExecutable` | function | `(source: string, target: string) => void` | Finalizes a built executable by durably flushing it to disk and atomically moving it into place. |
143
+ | `syncDirectory` | function | `(path: string) => void` | Fsyncs a directory to durably persist a prior file rename/create within it. |
144
+ | `buildBlobConfig` | function | `(entry: SEAEntryOptions, blob: string, assets: Readonly<Record<string, string>> \| undefined, options?: SEABlobOptions) => Readonly<Record<string, unknown>>` | Builds the Node.js `--experimental-sea-config` JSON object for a SEA blob. |
145
+ | `patchSentinelFuse` | function | `(executable: string, fuse: string) => void` | Patches the sentinel fuse in a binary from `:0` to `:1`. |
146
+ | `buildELFNoteHeader` | function | `(resource: string, blobSize: number) => ELFNoteHeader` | Builds an ELF `PT_NOTE` entry's header bytes (namesz/descsz/type + padded name) for the SEA blob note, without the blob body itself. |
147
+ | `alignELFNoteSize` | function | `(value: number) => number` | Aligns an ELF note component size to its four-byte boundary. |
148
+ | `isPowerOfTwo` | function | `(value: number) => boolean` | Checks whether a number is a nonzero power of two. |
149
+ | `copyRange` | function | `(source: number, target: number, start: number, length: number, chunk?: number) => void` | Copies a byte range from one open file descriptor to another, streaming in fixed-size chunks instead of buffering the whole range in memory. |
150
+ | `openBrowser` | function | `(url: string) => void` | Launches the system default browser at an http(s) URL. |
151
+ | `SEAError` | class | `new (code: SEAErrorCode, message: string, context?: Readonly<Record<string, unknown>>) => SEAError` | Represents the coded base error for every failure raised by the SEA build. |
152
+ | `isSEAError` | function | `(value: unknown) => value is SEAError` | Checks whether a value is a `SEAError`. |
153
+ | `ShellError` | class | `new (message: string, stdout: Buffer, stderr: Buffer) => ShellError` | Represents an error thrown when a shell command executed through `executeShell` exits non-zero. |
154
+ | `isShellError` | function | `(value: unknown) => value is ShellError` | Checks whether a value is a `ShellError`. |
155
155
 
156
156
  ### Types
157
157
 
158
158
  A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. An extended interface's name comes before `plus`, with the members it adds after.
159
159
 
160
- | API | Kind | Shape | Summary |
161
- | ------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
162
- | `SEACompressionSize` | interface | `{ original, compressed, ratio }` | Represents a size comparison between original and compressed data. |
163
- | `SEACompressionMode` | type | `'generic' \| 'text' \| 'font'` | Names a Brotli compression mode. |
164
- | `SEACompressionResult` | interface | `{ input, output, size }` | Represents the result of compressing a single file. |
165
- | `SEACompressionManifest` | interface | `{ assets, total }` | Summarizes all compressed assets. |
166
- | `SEAProgress` | interface | `{ path, current, total }` | Represents the progress reported while compressing a directory. |
167
- | `SEACompressionHandler` | type | `(result: SEACompressionResult) => void` | Describes the callback `compressDirectory` invokes after each file it compresses. |
168
- | `SEABrotliOptions` | interface | `{ mode?, quality? }` | Controls how Brotli encodes one file. |
169
- | `SEACompressionOptions` | interface | `SEABrotliOptions plus { paths }` | Controls Brotli compression of one or more directories. |
170
- | `SEAPlatform` | interface | `{ executable, remove?, sign?, verify? }` | Represents a platform-specific SEA build configuration. |
171
- | `SEAShellOptions` | interface | `{ cwd?, env?, timeout?, signal? }` | Configures the execution of a shell command. |
172
- | `ExecutableFormat` | type | `'pe' \| 'elf' \| 'macho'` | Names an executable binary format detected from file header magic bytes. |
173
- | `ELFNoteHeader` | interface | `{ header, total }` | Holds an ELF `PT_NOTE` entry's header bytes and the on-disk size of the whole entry. |
174
- | `ELFProgramHeader` | interface | `{ type, flags, offset, vaddr, paddr, filesz, memsz, align }` | Holds one ELF64 program header entry. |
175
- | `PEResourceLeaf` | interface | `{ typeId, typeName, nameId, nameName, language, codePage, dataRVA, dataSize }` | Holds one leaf of a PE resource directory tree. |
176
- | `PEResourceEntry` | interface | `{ language, codePage, leafIndex, dataSize }` | Holds one language entry of a PE resource name directory. |
177
- | `PESection` | interface | `{ name, virtualSize, virtualAddress, rawSize, rawOffset, characteristics, headerOffset }` | Holds one PE section table entry. |
178
- | `InjectorOptions` | interface | `{ executable, resource, blob, fuse?, macho?, overwrite? }` | Configures the injection of a resource into an executable. |
179
- | `InjectorMachOOptions` | interface | `{ segment? }` | Configures Mach-O specific injector behavior. |
180
- | `InjectorInterface` | interface | `{ format } plus inject` | Represents a cross-platform binary resource injector. |
181
- | `AssetInput` | interface | `{ key, content, compressed? }` | Holds the minimal data needed to create an `AssetInterface`. |
182
- | `AssetInterface` | interface | `{ key, content, compressed }` | Represents a single named asset wrapping its key, content buffer, and compression flag. |
183
- | `AssetManagerEventMap` | type | `{ register, load, clear, error }` | Lists the events emitted by an `AssetManagerInterface`. |
184
- | `AssetManagerOptions` | interface | `{ on?, error?, root?, assets? }` | Configures the creation of an `AssetManagerInterface`. |
185
- | `AssetManagerInterface` | interface | `{ emitter, count } plus asset, assets, keys, register, load, clear, destroy` | Represents a named asset collection with SEA and disk loading. |
186
- | `SEAStatus` | type | `'idle' \| 'active' \| 'done' \| 'error'` | Names the overall status of the SEA build. |
187
- | `SEAErrorCode` | type | `'PLATFORM' \| 'ENTRY' \| 'ASSET' \| 'BLOB' \| 'FORMAT' \| 'INJECT' \| 'ROOM' \| 'FUSE' \| 'SIGN' \| 'SHELL' \| 'TIMEOUT' \| 'ABORT' \| 'OUTPUT' \| 'STATE' \| 'BROWSER'` | Names the machine-readable error code carried by every `SEAError`. |
188
- | `SEAEntryFormat` | type | `'cjs' \| 'esm'` | Names the SEA entry point module format. |
189
- | `SEAEntryOptions` | interface | `{ path, format? }` | Describes the SEA entry point. |
190
- | `SEABlobOptions` | interface | `{ cache?, snapshot? }` | Controls generated SEA blob behavior. |
191
- | `SEAEventMap` | type | `{ compress, progress, blob, assemble, complete, error }` | Lists the events emitted by a `SEAInterface`. |
192
- | `SEAOptions` | interface | `{ on?, error?, name, entry, output, assets?, compression?, windows?, root?, signal?, timeout?, blob? }` | Configures the creation of a SEA build. |
193
- | `SEAWindowsOptions` | interface | `{ terminal?, sign? }` | Configures Windows-specific SEA build behavior. |
194
- | `SEAWindowsSignOptions` | interface | `{ file?, password?, thumbprint?, timestamp?, digest? }` | Describes the Windows Authenticode signing options passed through to `signtool`. |
195
- | `SEAResult` | interface | `{ executable, platform, size, duration, compression?, signed, stripped, terminal? }` | Represents the result of a successful SEA build. |
196
- | `SEAInterface` | interface | `{ emitter, status } plus execute, destroy` | Represents a SEA build orchestrator. |
160
+ | Name | Kind | Signature | Summary |
161
+ | ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
162
+ | `SEACompressionSize` | interface | `{ original, compressed, ratio }` | Represents a size comparison between original and compressed data. |
163
+ | `SEACompressionMode` | type | `'generic' \| 'text' \| 'font'` | Names a Brotli compression mode. |
164
+ | `SEACompressionResult` | interface | `{ input, output, size }` | Represents the result of compressing a single file. |
165
+ | `SEACompressionManifest` | interface | `{ assets, total }` | Summarizes all compressed assets. |
166
+ | `SEAProgress` | interface | `{ path, current, total }` | Represents the progress reported while compressing a directory. |
167
+ | `SEACompressionHandler` | type | `(result: SEACompressionResult) => void` | Describes the callback `compressDirectory` invokes after each file it compresses. |
168
+ | `SEABrotliOptions` | interface | `{ mode?, quality? }` | Controls how Brotli encodes one file. |
169
+ | `SEACompressionOptions` | interface | `{ paths }` | Controls Brotli compression of one or more directories. |
170
+ | `SEAPlatform` | interface | `{ executable, remove?, sign?, verify? }` | Represents a platform-specific SEA build configuration. |
171
+ | `SEAShellOptions` | interface | `{ cwd?, env?, timeout?, signal? }` | Configures the execution of a shell command. |
172
+ | `ExecutableFormat` | type | `'pe' \| 'elf' \| 'macho'` | Names an executable binary format detected from file header magic bytes. |
173
+ | `ELFNoteHeader` | interface | `{ header, total }` | Holds an ELF `PT_NOTE` entry's header bytes and the on-disk size of the whole entry. |
174
+ | `ELFProgramHeader` | interface | `{ type, flags, offset, vaddr, paddr, filesz, memsz, align }` | Holds one ELF64 program header entry. |
175
+ | `PEResourceLeaf` | interface | `{ typeId, typeName, nameId, nameName, language, codePage, dataRVA, dataSize }` | Holds one leaf of a PE resource directory tree. |
176
+ | `PEResourceEntry` | interface | `{ language, codePage, leafIndex, dataSize }` | Holds one language entry of a PE resource name directory. |
177
+ | `PESection` | interface | `{ name, virtualSize, virtualAddress, rawSize, rawOffset, characteristics, headerOffset }` | Holds one PE section table entry. |
178
+ | `InjectorOptions` | interface | `{ executable, resource, blob, fuse?, macho?, overwrite? }` | Configures the injection of a resource into an executable. |
179
+ | `InjectorMachOOptions` | interface | `{ segment? }` | Configures Mach-O specific injector behavior. |
180
+ | `InjectorInterface` | interface | `{ format, inject() }` | Represents a cross-platform binary resource injector. |
181
+ | `AssetInput` | interface | `{ key, content, compressed? }` | Holds the minimal data needed to create an `AssetInterface`. |
182
+ | `AssetInterface` | interface | `{ key, content, compressed }` | Represents a single named asset wrapping its key, content buffer, and compression flag. |
183
+ | `AssetManagerEventMap` | type | `{ readonly register: readonly [asset: AssetInterface]; readonly load: readonly [keys: readonly string[]]; readonly clear: readonly []; readonly error: readonly [error: unknown]; }` | Lists the events emitted by an `AssetManagerInterface`. |
184
+ | `AssetManagerOptions` | interface | `{ on?, error?, root?, assets? }` | Configures the creation of an `AssetManagerInterface`. |
185
+ | `AssetManagerInterface` | interface | `{ emitter, count, asset(), assets(), keys(), register(), load(), clear(), destroy() }` | Represents a named asset collection with SEA and disk loading. |
186
+ | `SEAStatus` | type | `'idle' \| 'active' \| 'done' \| 'error'` | Names the overall status of the SEA build. |
187
+ | `SEAErrorCode` | type | `'PLATFORM' \| 'ENTRY' \| 'ASSET' \| 'BLOB' \| 'FORMAT' \| 'INJECT' \| 'ROOM' \| 'FUSE' \| 'SIGN' \| 'SHELL' \| 'TIMEOUT' \| 'ABORT' \| 'OUTPUT' \| 'STATE' \| 'BROWSER'` | Names the machine-readable error code carried by every `SEAError`. |
188
+ | `SEAEntryFormat` | type | `'cjs' \| 'esm'` | Names the SEA entry point module format. |
189
+ | `SEAEntryOptions` | interface | `{ path, format? }` | Describes the SEA entry point. |
190
+ | `SEABlobOptions` | interface | `{ cache?, snapshot? }` | Controls generated SEA blob behavior. |
191
+ | `SEAEventMap` | type | `{ readonly compress: readonly [compression: SEACompressionManifest \| undefined]; readonly progress: readonly [progress: SEAProgress]; readonly blob: readonly [blob: string]; readonly assemble: readonly [executable: string]; readonly complete: readonly [result: SEAResult]; readonly error: readonly [error: unknown]; }` | Lists the events emitted by a `SEAInterface`. |
192
+ | `SEAOptions` | interface | `{ on?, error?, name, entry, output, assets?, compression?, windows?, root?, signal?, timeout?, blob? }` | Configures the creation of a SEA build. |
193
+ | `SEAWindowsOptions` | interface | `{ terminal?, sign? }` | Configures Windows-specific SEA build behavior. |
194
+ | `SEAWindowsSignOptions` | interface | `{ file?, password?, thumbprint?, timestamp?, digest? }` | Describes the Windows Authenticode signing options passed through to `signtool`. |
195
+ | `SEAResult` | interface | `{ executable, platform, size, duration, compression?, signed, stripped, terminal? }` | Represents the result of a successful SEA build. |
196
+ | `SEAInterface` | interface | `{ emitter, status, execute(), destroy() }` | Represents a SEA build orchestrator. |
197
197
 
198
198
  ## Methods
199
199