@wildshard/upload 0.0.0 → 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.
- package/package.json +26 -8
- package/src/cli/account/account.ts +199 -0
- package/src/cli/account/command.ts +193 -0
- package/src/cli/account/key.ts +154 -0
- package/src/cli/args.ts +100 -0
- package/src/cli/audio/audio.ts +39 -0
- package/src/cli/delete/delete.ts +258 -0
- package/src/cli/hero/hero.ts +163 -0
- package/src/cli/hero/scene-card.ts +46 -0
- package/src/cli/hero/stamp.ts +300 -0
- package/src/cli/report.ts +20 -0
- package/src/cli/shardfile/command.ts +49 -0
- package/src/cli/shardfile/shardfile.ts +192 -0
- package/src/cli/upload/api.ts +286 -0
- package/src/cli/upload/command.ts +239 -0
- package/src/cli/upload/completion.ts +80 -0
- package/src/cli/upload/compress.ts +55 -0
- package/src/cli/upload/hero-gate.ts +208 -0
- package/src/cli/upload/hero.ts +62 -0
- package/src/cli/upload/image-size.ts +89 -0
- package/src/cli/upload/placement.ts +132 -0
- package/src/cli/upload/provenance.ts +204 -0
- package/src/cli/upload/signature.ts +39 -0
- package/src/cli/upload/status-body.ts +41 -0
- package/src/cli/upload/status.ts +176 -0
- package/src/cli/upload/upload.ts +298 -0
- package/src/cli/upload/validate.ts +92 -0
- package/src/cli/upload/wire.ts +189 -0
- package/src/sharddev/draft.ts +11 -0
- package/src/sharddev/refusals.ts +329 -0
- package/src/sharddev/shardSource.ts +75 -0
- package/README.md +0 -3
|
@@ -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 }
|