@wildshard/upload 0.0.0-stage → 0.4.0

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.
@@ -0,0 +1,208 @@
1
+ import { cardDigest } from './hero.ts'
2
+ import { imageSize } from './image-size.ts'
3
+
4
+ import type { Carded, HeroCard } from './hero.ts'
5
+ import type { Size } from './image-size.ts'
6
+
7
+ // The hero gate (meta HERO-GATE HG2). Jake, 2026-11-17 ~14:32 Cancún: "in
8
+ // zone select there are zones without hero images that's bad, that should
9
+ // be failing at either the sharddev cli or the api-server level or both."
10
+ //
11
+ // The same rules api-server's commit runs (its `shardfile/hero-gate.ts`),
12
+ // run on the author's machine first, over the tarball's members. A hero is
13
+ // the zone-select card's three images at the sizes `wildshard hero`
14
+ // captures (GUIDE "The hero"). The card is the discovery mount's
15
+ // (`mounts/shardfiles/<folder>/discovery.json` `data.card`, what the cook
16
+ // serves a placed zone's card), else the manifest's, else the
17
+ // presentation's: api-server's order. A
18
+ // card that is missing, the generated `data:` placeholder, not carried,
19
+ // not an image or the wrong size refuses with its rule and the fix.
20
+
21
+ type Slot = keyof HeroCard
22
+
23
+ type HeroRule = 'hero-missing' | 'hero-generated' | 'hero-image' | 'hero-size'
24
+
25
+ type HeroVerdict =
26
+ | Readonly<{ ok: true; digest: string }>
27
+ | Readonly<{ ok: false; rule: HeroRule; reason: string }>
28
+
29
+ /** What the gate needs of the validated shard besides its files. */
30
+ type HeroShard = Carded & Readonly<{ identity: Readonly<{ slug: string }> }>
31
+
32
+ type Members = ReadonlyMap<string, Readonly<Uint8Array>>
33
+
34
+ const SLOTS: readonly Slot[] = ['thumb', 'portrait', 'landscape']
35
+ const SIZES: Readonly<Record<Slot, Size>> = {
36
+ thumb: { width: 640, height: 360 },
37
+ portrait: { width: 804, height: 1626 },
38
+ landscape: { width: 1600, height: 900 },
39
+ }
40
+ const SHOWN = 120
41
+ const ONLY = 1
42
+ const START = 0
43
+ const BLOB_HASH = /^[a-f0-9]{64}$/u
44
+ const BLOB_URL =
45
+ /^\/shardfiles\/[^/]+\/blobs\/image\/(?<hash>[a-f0-9]{64})\.[a-z0-9]+$/u
46
+ const IMAGE_PATH =
47
+ /^(?:blobs|mounts\/shardfiles\/[^/]+\/blobs)\/image\/(?<hash>[a-f0-9]{64})\.(?:jpe?g|png|webp)$/u
48
+ const DISCOVERY_PATH = /^mounts\/shardfiles\/[^/]+\/discovery\.json$/u
49
+ const CAPTURE =
50
+ 'capture it from a served build with `wildshard hero <shard> --base <url>`, then build, pack and upload again'
51
+
52
+ function isCard(value: unknown): value is HeroCard {
53
+ return (
54
+ typeof value === 'object' &&
55
+ value !== null &&
56
+ SLOTS.every(
57
+ (slot: Slot): boolean => typeof Reflect.get(value, slot) === 'string',
58
+ )
59
+ )
60
+ }
61
+
62
+ /** The value at `key` of an object, else undefined. */
63
+ function at(value: unknown, key: string): unknown {
64
+ return typeof value === 'object' && value !== null
65
+ ? Reflect.get(value, key)
66
+ : undefined
67
+ }
68
+
69
+ /** A discovery document's `data.card`, if it has a whole one. */
70
+ function cardOf(bytes: Readonly<Uint8Array>): HeroCard | undefined {
71
+ try {
72
+ const document: unknown = JSON.parse(new TextDecoder().decode(bytes))
73
+ const card = at(at(document, 'data'), 'card')
74
+ return isCard(card) ? card : undefined
75
+ } catch {
76
+ return undefined
77
+ }
78
+ }
79
+
80
+ /** The discovery mount's card: the shard's own folder's, else the only mount's. */
81
+ function discoveryCard(slug: string, files: Members): HeroCard | undefined {
82
+ const mounts = [...files.keys()].filter((path: string): boolean =>
83
+ DISCOVERY_PATH.test(path),
84
+ )
85
+ const own = `mounts/shardfiles/${slug}/discovery.json`
86
+ const [only] = mounts.length === ONLY ? mounts : []
87
+ const bytes = files.get(mounts.includes(own) ? own : (only ?? ''))
88
+ return bytes === undefined ? undefined : cardOf(bytes)
89
+ }
90
+
91
+ /** The shard's card: the discovery mount's, else the manifest's, else the presentation's (api-server's order). */
92
+ function heroCard(
93
+ shard: Readonly<HeroShard>,
94
+ files: Members,
95
+ ): HeroCard | undefined {
96
+ return (
97
+ discoveryCard(shard.identity.slug, files) ??
98
+ shard.manifest?.card ??
99
+ shard.presentation?.card
100
+ )
101
+ }
102
+
103
+ /** Each image member's bytes by blob hash. */
104
+ function imagesOf(files: Members): ReadonlyMap<string, Readonly<Uint8Array>> {
105
+ const images = new Map<string, Readonly<Uint8Array>>()
106
+ for (const [path, bytes] of files) {
107
+ const hash = IMAGE_PATH.exec(path)?.groups?.['hash']
108
+ if (hash !== undefined) {
109
+ images.set(hash, bytes)
110
+ }
111
+ }
112
+ return images
113
+ }
114
+
115
+ function refused(rule: HeroRule, reason: string): HeroVerdict {
116
+ return { ok: false, rule, reason: `[${rule}] ${reason}; ${CAPTURE}` }
117
+ }
118
+
119
+ function sizeText({ width, height }: Size): string {
120
+ return `${String(width)}x${String(height)}`
121
+ }
122
+
123
+ /** An image's refusal, if it is not an image or not its slot's size. */
124
+ function sizeRefusal(
125
+ named: string,
126
+ slot: Slot,
127
+ bytes: Readonly<Uint8Array>,
128
+ ): HeroVerdict | undefined {
129
+ const size = imageSize(bytes)
130
+ if (size === undefined) {
131
+ return refused('hero-image', `${named} is not a PNG, JPEG or WebP image`)
132
+ }
133
+ const want = SIZES[slot]
134
+ return size.width === want.width && size.height === want.height
135
+ ? undefined
136
+ : refused(
137
+ 'hero-size',
138
+ `${named} is ${sizeText(size)}, not ${sizeText(want)}`,
139
+ )
140
+ }
141
+
142
+ /** One card image's refusal, if it breaks a rule. */
143
+ function slotRefusal(
144
+ {
145
+ named,
146
+ slot,
147
+ image,
148
+ }: Readonly<{ named: string; slot: Slot; image: string }>,
149
+ images: ReadonlyMap<string, Readonly<Uint8Array>>,
150
+ ): HeroVerdict | undefined {
151
+ if (image.startsWith('data:')) {
152
+ return refused(
153
+ 'hero-generated',
154
+ `${named} is the generated placeholder card, not a captured hero`,
155
+ )
156
+ }
157
+ const hash = BLOB_HASH.test(image)
158
+ ? image
159
+ : BLOB_URL.exec(image)?.groups?.['hash']
160
+ const bytes = hash === undefined ? undefined : images.get(hash)
161
+ if (bytes === undefined) {
162
+ return refused(
163
+ 'hero-image',
164
+ `${named} (${image.slice(START, SHOWN)}) is not an image this shard file carries`,
165
+ )
166
+ }
167
+ return sizeRefusal(named, slot, bytes)
168
+ }
169
+
170
+ /** Whether the shard's hero is present, captured, carried, an image and the right size; its digest when it is. */
171
+ function heroVerdict(shard: Readonly<HeroShard>, files: Members): HeroVerdict {
172
+ const card = heroCard(shard, files)
173
+ const { slug } = shard.identity
174
+ if (card === undefined) {
175
+ return refused(
176
+ 'hero-missing',
177
+ `${slug} has no hero (no card in its discovery, manifest or presentation)`,
178
+ )
179
+ }
180
+ const images = imagesOf(files)
181
+ const refusals = SLOTS.map((slot: Slot): HeroVerdict | undefined =>
182
+ slotRefusal(
183
+ { named: `${slug}'s hero ${slot}`, slot, image: card[slot] },
184
+ images,
185
+ ),
186
+ )
187
+ return (
188
+ refusals.find(
189
+ (row: HeroVerdict | undefined): boolean => row !== undefined,
190
+ ) ?? { ok: true, digest: cardDigest(card) }
191
+ )
192
+ }
193
+
194
+ /** Upload's refusal (HG2, Jake 2026-11-17): no zone reaches zone select without a hero. */
195
+ function assertHero(hero: HeroVerdict): void {
196
+ if (!hero.ok) {
197
+ throw new Error(hero.reason)
198
+ }
199
+ }
200
+
201
+ export {
202
+ type HeroRule,
203
+ type HeroShard,
204
+ type HeroVerdict,
205
+ assertHero,
206
+ heroCard,
207
+ heroVerdict,
208
+ }
@@ -0,0 +1,62 @@
1
+ import { createHash } from 'node:crypto'
2
+
3
+ // The hero digest (meta SHARD-AUTHORING UP4, J306, choice 4), computed as
4
+ // api-server computes it (`src/server/shardfile/hero.ts`, `79f5ca1`), so
5
+ // the upload pre-check refuses exactly what the commit would. A shard's
6
+ // hero is its SHARD SELECT card, three images; the digest is the SHA-256
7
+ // of `thumb:<hash>\nportrait:<hash>\nlandscape:<hash>`, each the image's
8
+ // blob hash.
9
+ //
10
+ // The card is the manifest's (`manifest.card`, the packed URLs every live
11
+ // shard and the template carry), else the presentation's (bare blob
12
+ // hashes). A packed URL names its blob,
13
+ // `/shardfiles/<folder>/blobs/image/<hash>.<ext>`; a generated `data:`
14
+ // card has no blob, so its hash is the SHA-256 of the URL. A shard with no
15
+ // card has no digest.
16
+
17
+ interface HeroCard {
18
+ readonly thumb: string
19
+ readonly portrait: string
20
+ readonly landscape: string
21
+ }
22
+
23
+ /** The two places a validated shard file carries its card. */
24
+ interface Carded {
25
+ readonly manifest?: Readonly<{ card: HeroCard }> | undefined
26
+ readonly presentation?: Readonly<{ card: HeroCard }> | undefined
27
+ }
28
+
29
+ const BLOB_HASH = /^[a-f0-9]{64}$/u
30
+ const BLOB_URL =
31
+ /^\/shardfiles\/[^/]+\/blobs\/image\/(?<hash>[a-f0-9]{64})\.[a-z0-9]+$/u
32
+
33
+ function sha256(text: string): string {
34
+ return createHash('sha256').update(text).digest('hex')
35
+ }
36
+
37
+ /** One card image's blob hash: a bare hash, the hash a packed URL names, else the URL's own SHA-256. */
38
+ function imageHash(image: string): string {
39
+ if (BLOB_HASH.test(image)) {
40
+ return image
41
+ }
42
+ return BLOB_URL.exec(image)?.groups?.['hash'] ?? sha256(image)
43
+ }
44
+
45
+ /** The digest of a card's three images, in choice 4's order. */
46
+ function cardDigest(card: HeroCard): string {
47
+ return sha256(
48
+ [
49
+ `thumb:${imageHash(card.thumb)}`,
50
+ `portrait:${imageHash(card.portrait)}`,
51
+ `landscape:${imageHash(card.landscape)}`,
52
+ ].join('\n'),
53
+ )
54
+ }
55
+
56
+ /** The shard's hero digest, or undefined when it has no card. */
57
+ function heroHashOf(shard: Readonly<Carded>): string | undefined {
58
+ const card = shard.manifest?.card ?? shard.presentation?.card
59
+ return card === undefined ? undefined : cardDigest(card)
60
+ }
61
+
62
+ export { type Carded, type HeroCard, cardDigest, heroHashOf }
@@ -0,0 +1,89 @@
1
+ // oxlint-disable eslint/no-magic-numbers, eslint/no-bitwise, unicorn/number-literal-case -- a byte-format reader: its offsets and masks are the PNG, JPEG and WebP specs' own
2
+
3
+ // An image's pixel size from its first bytes (meta HERO-GATE HG3): PNG's
4
+ // IHDR, JPEG's first SOF segment, WebP's VP8X, VP8 or VP8L header. Anything
5
+ // else is not an image a hero may be.
6
+
7
+ interface Size {
8
+ readonly width: number
9
+ readonly height: number
10
+ }
11
+
12
+ const at8 = (bytes: Readonly<Uint8Array>, at: number): number => bytes[at] ?? 0
13
+ const be16 = (bytes: Readonly<Uint8Array>, at: number): number =>
14
+ (at8(bytes, at) << 8) | at8(bytes, at + 1)
15
+ const le16 = (bytes: Readonly<Uint8Array>, at: number): number =>
16
+ at8(bytes, at) | (at8(bytes, at + 1) << 8)
17
+ const le24 = (bytes: Readonly<Uint8Array>, at: number): number =>
18
+ le16(bytes, at) | (at8(bytes, at + 2) << 16)
19
+ const be32 = (bytes: Readonly<Uint8Array>, at: number): number =>
20
+ be16(bytes, at) * 0x1_00_00 + be16(bytes, at + 2)
21
+ const ascii = (
22
+ bytes: Readonly<Uint8Array>,
23
+ at: number,
24
+ length: number,
25
+ ): string => String.fromCodePoint(...bytes.subarray(at, at + length))
26
+
27
+ function pngSize(bytes: Readonly<Uint8Array>): Size | undefined {
28
+ return ascii(bytes, 1, 3) === 'PNG' && ascii(bytes, 12, 4) === 'IHDR'
29
+ ? { width: be32(bytes, 16), height: be32(bytes, 20) }
30
+ : undefined
31
+ }
32
+
33
+ /** SOF0 to SOF15, less DHT (C4), JPG (C8) and DAC (CC). */
34
+ function isFrame(marker: number): boolean {
35
+ return (
36
+ marker >= 0xc0 &&
37
+ marker <= 0xcf &&
38
+ marker !== 0xc4 &&
39
+ marker !== 0xc8 &&
40
+ marker !== 0xcc
41
+ )
42
+ }
43
+
44
+ function jpegSize(bytes: Readonly<Uint8Array>): Size | undefined {
45
+ let at = 2
46
+ while (at + 9 <= bytes.length && at8(bytes, at) === 0xff) {
47
+ if (isFrame(at8(bytes, at + 1))) {
48
+ return { width: be16(bytes, at + 7), height: be16(bytes, at + 5) }
49
+ }
50
+ at += 2 + be16(bytes, at + 2)
51
+ }
52
+ return undefined
53
+ }
54
+
55
+ function webpSize(bytes: Readonly<Uint8Array>): Size | undefined {
56
+ const kind = ascii(bytes, 12, 4)
57
+ if (kind === 'VP8X') {
58
+ return { width: le24(bytes, 24) + 1, height: le24(bytes, 27) + 1 }
59
+ }
60
+ if (kind === 'VP8 ') {
61
+ return {
62
+ width: le16(bytes, 26) & 0x3f_ff,
63
+ height: le16(bytes, 28) & 0x3f_ff,
64
+ }
65
+ }
66
+ if (kind === 'VP8L') {
67
+ const bits = le16(bytes, 21) + le16(bytes, 23) * 0x1_00_00
68
+ return {
69
+ width: (bits & 0x3f_ff) + 1,
70
+ height: ((bits >>> 14) & 0x3f_ff) + 1,
71
+ }
72
+ }
73
+ return undefined
74
+ }
75
+
76
+ /** An image's size, or undefined when the bytes are not a PNG, JPEG or WebP (or too few to tell). */
77
+ function imageSize(bytes: Readonly<Uint8Array>): Size | undefined {
78
+ if (at8(bytes, 0) === 0x89) {
79
+ return pngSize(bytes)
80
+ }
81
+ if (at8(bytes, 0) === 0xff && at8(bytes, 1) === 0xd8) {
82
+ return jpegSize(bytes)
83
+ }
84
+ return ascii(bytes, 0, 4) === 'RIFF' && ascii(bytes, 8, 4) === 'WEBP'
85
+ ? webpSize(bytes)
86
+ : undefined
87
+ }
88
+
89
+ export { type Size, imageSize }
@@ -0,0 +1,132 @@
1
+ import { safeParse } from 'valibot'
2
+
3
+ import { PlacementSchema } from './wire.ts'
4
+
5
+ import type { Channel } from './api.ts'
6
+ import type { CommitAnswer, Placement } from './wire.ts'
7
+
8
+ // What the upload says about the grid (meta SHARD-AUTHORING SA32, J314):
9
+ // the cell the API gave the shard, or why it gave none, then the
10
+ // `/slug/<slug>` link on each channel the upload moved. api-server's SA30
11
+ // answers `placement` only while its `GRID_AUTOPLACE` is on, and then not
12
+ // for a shard with no cell past its first upload, so a missing answer says
13
+ // "no new cell" rather than guess which. Only a first upload (catalogue
14
+ // number 1) takes a cell: `--no-place` later leaves a held cell where it
15
+ // is, so that line says the grid was left alone. The page behind the link
16
+ // is SA36 and SA37's, not built yet, and the line says so.
17
+
18
+ /** The API's words for `place: false` and for a failed grid step (SA30). */
19
+ const NOT_ASKED = 'not placed (place: false)'
20
+ const FAILED = 'not placed: the grid step failed'
21
+ const FIRST_UPLOAD = 1
22
+ const NO_PLACE_LINE = 'not placed (--no-place)'
23
+ const LEFT_ALONE_LINE = 'grid left as it was (--no-place)'
24
+ const NO_ANSWER_LINE =
25
+ "no new cell: grid placement is off on the API, or this is not the shard's first upload"
26
+ const FAILED_LINE =
27
+ 'not placed: the grid step failed; run the same upload again to retry'
28
+ const UNREAD_LINE = "grid: the API's placement answer was not understood"
29
+ const PAGE_NOT_BUILT = '(page not built yet)'
30
+
31
+ /** Each channel's host (GUIDE.md section 5). */
32
+ const HOSTS = {
33
+ preview: 'preview.wildshard.io',
34
+ staging: 'staging.wildshard.io',
35
+ production: 'play.wildshard.io',
36
+ } as const
37
+
38
+ type ChannelName = keyof typeof HOSTS
39
+
40
+ interface Asked {
41
+ readonly place: boolean
42
+ /** The answer's catalogue number: 1 is the shard's first upload. */
43
+ readonly revision: number
44
+ readonly moved: readonly ChannelName[]
45
+ }
46
+
47
+ /** The grid line for a placed shard, naming any moved channel whose grid lacks it. */
48
+ function placedLine(
49
+ placement: Extract<Placement, { placed: true }>,
50
+ moved: readonly ChannelName[],
51
+ ): string {
52
+ const [col, row] = placement.cell
53
+ const on = placement.channels.join(', ')
54
+ const missed = moved
55
+ .filter((name: ChannelName): boolean => !placement.channels.includes(name))
56
+ .map((name: ChannelName): string => `; not on ${name}'s grid`)
57
+ return `placed at (${String(col)},${String(row)}) on ${on}${missed.join('')}`
58
+ }
59
+
60
+ /** The `--no-place` line: a first upload took no cell; a later one left the grid alone. */
61
+ function noPlaceLine(asked: Asked): string {
62
+ return asked.revision === FIRST_UPLOAD ? NO_PLACE_LINE : LEFT_ALONE_LINE
63
+ }
64
+
65
+ /** The line for `{ placed: false }`, by the API's reason. */
66
+ function notPlacedLine(reason: string, asked: Asked): string {
67
+ if (reason === NOT_ASKED) {
68
+ return noPlaceLine(asked)
69
+ }
70
+ return reason.startsWith(FAILED) ? FAILED_LINE : reason
71
+ }
72
+
73
+ /** The grid line: the cell, or why there is none. */
74
+ function gridLine(raw: unknown, asked: Asked): string {
75
+ if (raw === undefined) {
76
+ return asked.place ? NO_ANSWER_LINE : noPlaceLine(asked)
77
+ }
78
+ const parsed = safeParse(PlacementSchema, raw)
79
+ if (!parsed.success) {
80
+ return UNREAD_LINE
81
+ }
82
+ const placement = parsed.output
83
+ return placement.placed
84
+ ? placedLine(placement, asked.moved)
85
+ : notPlacedLine(placement.reason, asked)
86
+ }
87
+
88
+ /** The channels an upload moves (J301); a revived shard moves preview only (DEL7). */
89
+ function movedChannels(
90
+ channel: Channel,
91
+ revived: boolean,
92
+ ): readonly ChannelName[] {
93
+ if (revived) {
94
+ return ['preview']
95
+ }
96
+ return channel === 'production'
97
+ ? ['preview', 'staging', 'production']
98
+ : ['preview', 'staging']
99
+ }
100
+
101
+ /**
102
+ * Meta STAGING-BUGBASH SB35: api-server recorded the upload, but its format
103
+ * is above the one the channel serves, so no pointer moves there until the
104
+ * channel's format does (a release call, not the author's).
105
+ */
106
+ function heldLines(answer: CommitAnswer, channel: Channel): readonly string[] {
107
+ return answer.held === undefined
108
+ ? []
109
+ : [
110
+ `warning: held: ${answer.held}; nothing goes live on ${channel} until that channel's format moves`,
111
+ ]
112
+ }
113
+
114
+ /** The grid line, then one `/slug/<slug>` link per channel moved. */
115
+ function placementLines(
116
+ answer: CommitAnswer,
117
+ options: Readonly<{ channel: Channel; place: boolean }>,
118
+ ): readonly string[] {
119
+ const moved = movedChannels(options.channel, answer.revived === true)
120
+ const asked = { place: options.place, revision: answer.revision, moved }
121
+ const links = moved.map(
122
+ (name: ChannelName): string =>
123
+ `${name}: https://${HOSTS[name]}/slug/${answer.shard} ${PAGE_NOT_BUILT}`,
124
+ )
125
+ return [
126
+ ...heldLines(answer, options.channel),
127
+ gridLine(answer.placement, asked),
128
+ ...links,
129
+ ]
130
+ }
131
+
132
+ export { placementLines }
@@ -0,0 +1,204 @@
1
+ import { spawn } from 'node:child_process'
2
+ import { once } from 'node:events'
3
+ import { readFile } from 'node:fs/promises'
4
+ import path from 'node:path'
5
+ import { text as readAll } from 'node:stream/consumers'
6
+
7
+ import { object, optional, safeParse, string } from 'valibot'
8
+
9
+ // What every upload names (API-CLOUDFLARE AC16, J275 V1): the shard version
10
+ // and the commit of the shard project it was built from. `--version`
11
+ // defaults to the project's package.json version and `--commit` to its git
12
+ // HEAD, and a HEAD with uncommitted changes to tracked files is refused, as
13
+ // it does not describe the bytes. Untracked files (the packed tarball, build
14
+ // output) are not dirt, as in `git describe --dirty`. The checks match the
15
+ // API's, so a bad value fails here, before any bytes move.
16
+ //
17
+ // J306 (SHARD-AUTHORING UP3) adds the versions the shard was built with:
18
+ // sharddev's own, and engine's and shard-format's from the package.json
19
+ // each name resolves to from the shard project, the nearest
20
+ // node_modules/<name> at or above it. shard-format is
21
+ // `@wildshard/shard-format`, or the `@wildshard/format` alias until the J308
22
+ // pins land. A shard with neither installed falls back to the copy this
23
+ // sharddev carries, which is what its build ran with.
24
+
25
+ const VERSION = /^(?:0|[1-9]\d{0,8})\.(?:0|[1-9]\d{0,8})\.(?:0|[1-9]\d{0,8})$/u
26
+ const COMMIT = /^[\da-f]{40}$/u
27
+ const PACKAGE_JSON = 'package.json'
28
+ const GIT_OK = 0
29
+
30
+ const PackageJsonSchema = object({ version: optional(string()) })
31
+
32
+ const ENGINE = ['@wildshard/engine']
33
+ const SHARD_FORMAT = ['@wildshard/shard-format', '@wildshard/format']
34
+ // The fallback install when the caller names none: upload's own folder, from here up. The sdk names its own folder
35
+ // (SDK-SPLIT SP2b), since upload's package does not depend on the engine.
36
+ const SHARDDEV_DIR = import.meta.dirname
37
+
38
+ interface ProvenanceRequest {
39
+ /** Where `wildshard upload` runs: inside the shard project. */
40
+ readonly cwd: string
41
+ /** The running `wildshard`'s own version; the caller reads it, so upload never reads the sdk's package.json (SP2a). */
42
+ readonly sharddev: string
43
+ /** Where the running `wildshard` resolves its own installs when the shard has none (the sdk's folder). */
44
+ readonly installDir?: string | undefined
45
+ /** `--version`, if passed. */
46
+ readonly version?: string | undefined
47
+ /** `--commit`, if passed. */
48
+ readonly commit?: string | undefined
49
+ }
50
+
51
+ interface Provenance {
52
+ readonly version: string
53
+ readonly commit: string
54
+ /** The sharddev that uploads (J306). */
55
+ readonly sharddev: string
56
+ /** The engine the shard resolves (J306). */
57
+ readonly engine: string
58
+ /** The shard-format the shard resolves (J306). */
59
+ readonly shardFormat: string
60
+ }
61
+
62
+ async function readIfThere(file: string): Promise<string | undefined> {
63
+ try {
64
+ return await readFile(file, 'utf8')
65
+ } catch (error: unknown) {
66
+ if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
67
+ return undefined
68
+ }
69
+ throw error
70
+ }
71
+ }
72
+
73
+ /** The nearest package.json at or above `dir`, and its text. */
74
+ async function nearestPackage(
75
+ dir: string,
76
+ ): Promise<Readonly<{ file: string; text: string }> | undefined> {
77
+ const file = path.join(dir, PACKAGE_JSON)
78
+ const text = await readIfThere(file)
79
+ if (text !== undefined) {
80
+ return { file, text }
81
+ }
82
+ const parent = path.dirname(dir)
83
+ return parent === dir ? undefined : await nearestPackage(parent)
84
+ }
85
+
86
+ async function projectVersion(cwd: string): Promise<string> {
87
+ const found = await nearestPackage(path.resolve(cwd))
88
+ if (found === undefined) {
89
+ throw new Error(
90
+ `no ${PACKAGE_JSON} at or above ${cwd}; pass --version X.Y.Z`,
91
+ )
92
+ }
93
+ const parsed = safeParse(PackageJsonSchema, JSON.parse(found.text))
94
+ const version = parsed.success ? parsed.output.version : undefined
95
+ if (version === undefined) {
96
+ throw new Error(`no version in ${found.file}; pass --version X.Y.Z`)
97
+ }
98
+ return version
99
+ }
100
+
101
+ async function git(cwd: string, args: readonly string[]): Promise<string> {
102
+ const child = spawn('git', [...args], {
103
+ cwd,
104
+ stdio: ['ignore', 'pipe', 'ignore'],
105
+ })
106
+ const output = readAll(child.stdout)
107
+ try {
108
+ await once(child, 'close')
109
+ } catch {
110
+ // No git, or no such folder: the same advice.
111
+ }
112
+ if (child.exitCode !== GIT_OK) {
113
+ throw new Error(`${cwd} is not a git checkout; pass --commit <sha>`)
114
+ }
115
+ const out = await output
116
+ return out.trim()
117
+ }
118
+
119
+ async function headCommit(cwd: string): Promise<string> {
120
+ const head = await git(cwd, ['rev-parse', 'HEAD'])
121
+ const dirty = await git(cwd, [
122
+ 'status',
123
+ '--porcelain',
124
+ '--untracked-files=no',
125
+ ])
126
+ if (dirty !== '') {
127
+ throw new Error(
128
+ `the shard source has uncommitted changes (git status in ${cwd}); commit them, or pass --commit <sha> for bytes built elsewhere`,
129
+ )
130
+ }
131
+ return head
132
+ }
133
+
134
+ /** The first of `names` installed at `dir` or above, and its version. */
135
+ async function installedAt(
136
+ dir: string,
137
+ names: readonly string[],
138
+ ): Promise<Readonly<{ name: string; file: string; text: string }> | undefined> {
139
+ for (const name of names) {
140
+ const file = path.join(dir, 'node_modules', name, PACKAGE_JSON)
141
+ // oxlint-disable-next-line no-await-in-loop -- the first name found wins
142
+ const text = await readIfThere(file)
143
+ if (text !== undefined) {
144
+ return { name, file, text }
145
+ }
146
+ }
147
+ const parent = path.dirname(dir)
148
+ return parent === dir ? undefined : await installedAt(parent, names)
149
+ }
150
+
151
+ /** The version of the first of `names` the shard, else sharddev, resolves. */
152
+ async function installedVersion(
153
+ cwd: string,
154
+ names: readonly string[],
155
+ installDir: string,
156
+ ): Promise<string> {
157
+ const found =
158
+ (await installedAt(path.resolve(cwd), names)) ??
159
+ (await installedAt(installDir, names))
160
+ if (found === undefined) {
161
+ throw new Error(
162
+ `${names.join(' or ')} is not installed at or above ${cwd}; run pnpm install in the shard repo`,
163
+ )
164
+ }
165
+ const parsed = safeParse(PackageJsonSchema, JSON.parse(found.text))
166
+ const version = parsed.success ? parsed.output.version : undefined
167
+ if (version === undefined || !VERSION.test(version)) {
168
+ throw new Error(
169
+ `${found.name} ${String(version)} (${found.file}) is not X.Y.Z`,
170
+ )
171
+ }
172
+ return version
173
+ }
174
+
175
+ /** The version and commit to send; throws what is missing or malformed. */
176
+ async function resolveProvenance(
177
+ request: ProvenanceRequest,
178
+ ): Promise<Provenance> {
179
+ const version = request.version ?? (await projectVersion(request.cwd))
180
+ if (!VERSION.test(version)) {
181
+ throw new Error(`--version ${version} is not X.Y.Z`)
182
+ }
183
+ const commit = request.commit ?? (await headCommit(request.cwd))
184
+ if (!COMMIT.test(commit)) {
185
+ throw new Error(`--commit ${commit} is not a full 40-hex sha`)
186
+ }
187
+ return {
188
+ version,
189
+ commit,
190
+ sharddev: request.sharddev,
191
+ engine: await installedVersion(
192
+ request.cwd,
193
+ ENGINE,
194
+ request.installDir ?? SHARDDEV_DIR,
195
+ ),
196
+ shardFormat: await installedVersion(
197
+ request.cwd,
198
+ SHARD_FORMAT,
199
+ request.installDir ?? SHARDDEV_DIR,
200
+ ),
201
+ }
202
+ }
203
+
204
+ export { type Provenance, type ProvenanceRequest, resolveProvenance }