@wildshard/sdk 0.2.11 → 0.2.12

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/GUIDE.md CHANGED
@@ -104,6 +104,11 @@ hero:
104
104
  Build then refuses a shard file whose content changed after the hero was stamped (`hero-stale`), and upload refuses a
105
105
  new version whose hero is the same as the previous version's (`hero-unchanged`). Section 6 has every hero refusal.
106
106
 
107
+ **A curated hero** is hand-picked art, not a capture. Put `"curated": true` in `hero.json` and the art is kept: after a
108
+ content change, `wildshard hero . --stamp-existing` re-stamps the images already there, and `wildshard hero . --base`
109
+ refuses rather than shoot the spawn view over them. A new version still needs a new picture (`hero-unchanged`): swap
110
+ the art, then `--stamp-existing`. Remove `curated` to capture again.
111
+
107
112
  ### Uploading
108
113
 
109
114
  An upload sends one shard file to the API (`https://api.wildshard.io`) and names its channel. Do these in order,
@@ -498,7 +503,8 @@ Codes `declared-costs`, `performance-targets` (shard-format checking the costs t
498
503
 
499
504
  The shard's content changed after its hero was captured, or the card names images `hero.json` has no stamp for. The
500
505
  hero must show the current world: capture it again (`wildshard hero . --base <url>`). Only if the images already show
501
- the current world, `wildshard hero . --stamp-existing`.
506
+ the current world, `wildshard hero . --stamp-existing`. A curated hero (`"curated": true` in `hero.json`, "The hero")
507
+ keeps its art: re-stamp it with `wildshard hero . --stamp-existing`.
502
508
 
503
509
  #### hero-not-in-product
504
510
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wildshard/sdk",
3
- "version": "0.2.11",
3
+ "version": "0.2.12",
4
4
  "description": "The author's toolbox: the `wildshard` CLI that bakes shard source into a shardfile, the author SDK, the local dev server (engine client against engine server), the explorers, arena and drafts tool.",
5
5
  "license": "UNLICENSED",
6
6
  "repository": {
@@ -81,6 +81,11 @@ async function selectCard(page, base, name) {
81
81
  }
82
82
 
83
83
  export async function captureHero(shard, given, { name = servedName(shard), log = console.info } = {}) {
84
+ // A curated card (hero.json "curated": true) is hand-picked art: a capture would put the spawn view over it.
85
+ const stampPath = join(shard, 'hero.json');
86
+ if (existsSync(stampPath) && JSON.parse(readFileSync(stampPath, 'utf8')).curated === true) {
87
+ throw new Error(`${stampPath}: this hero is curated ("curated": true), hand-picked art that is never recaptured; re-stamp it for new content with \`wildshard hero <source> --stamp-existing\`, or remove "curated" to capture this view`);
88
+ }
84
89
  const base = servedRoot(given);
85
90
  // Loaded here, so --stamp-existing needs no browser or engine to resolve.
86
91
  const [{ chromium }, { NAME_ASKED, saveFixture }, { KEYCHAIN_ARGS }] = await Promise.all([
@@ -91,7 +91,13 @@ async function stampExistingHero(shard: string): Promise<Adopted> {
91
91
  if (hero.state === 'fresh') {
92
92
  return { written: false, content: hero.content }
93
93
  }
94
- if (hero.stamped !== undefined && hero.stamped !== hero.content) {
94
+ // A curated hero (hero.json "curated": true) is hand-picked art that no
95
+ // spawn-view capture should replace: it is re-stamped over new content.
96
+ if (
97
+ hero.curated !== true &&
98
+ hero.stamped !== undefined &&
99
+ hero.stamped !== hero.content
100
+ ) {
95
101
  throw new Error(
96
102
  `the hero of ${path.basename(shard)} was stamped for other content (captured ${hero.captured ?? 'at an unknown time'}); the world has changed since, so only a capture fixes it, nothing stamped`,
97
103
  )
@@ -71,6 +71,9 @@ function refusal(shard: string, hero: HeroState): string {
71
71
  const name = path.basename(shard)
72
72
  const capture = `serve this candidate in an engine build, then capture it: ${captureCommand(shard)}`
73
73
  const adopt = `; or, only if the images already there show this content, stamp them with no capture: ${stampExistingCommand(shard)}`
74
+ if (hero.curated === true) {
75
+ return `the hero of ${name} is curated (${STAMP} "curated": true) and its stamp does not match this content or these images; keep the art and re-stamp it with no capture: ${stampExistingCommand(shard)}`
76
+ }
74
77
  if (hero.state === 'unstamped') {
75
78
  return `the hero of ${name} has no ${STAMP} stamp, so nothing says it shows this content; ${capture}${adopt}`
76
79
  }
@@ -20,22 +20,12 @@ const MANIFEST = 'manifest.json'
20
20
  const SLOTS = ['thumb', 'portrait', 'landscape'] as const
21
21
  // Generated, ignored, test or prose files are not the world a hero shows.
22
22
  // The directories are skipped at the shard folder's top level only.
23
- const SKIPPED_DIRECTORIES = new Set([
24
- '.cache',
25
- '.git',
26
- '.worktrees',
27
- 'dist',
28
- 'node_modules',
29
- 'public',
30
- 'tmp',
31
- ])
32
- const SKIPPED_SUFFIXES = [
33
- '.generated.ts',
34
- '.test.ts',
35
- '.test.mjs',
36
- '.md',
37
- '.DS_Store',
38
- ]
23
+ const SKIPPED_DIRECTORIES = new Set(
24
+ '.cache .git .worktrees dist node_modules public tmp'.split(' '),
25
+ )
26
+ const SKIPPED_SUFFIXES = '.generated.ts .test.ts .test.mjs .md .DS_Store'.split(
27
+ ' ',
28
+ )
39
29
  const NOT_FOUND = 'ENOENT'
40
30
  const VALUE = 1
41
31
  const NONE = 0
@@ -52,6 +42,7 @@ interface HeroState {
52
42
  readonly stamped?: string | undefined
53
43
  /** When the stamp says the hero was captured. */
54
44
  readonly captured?: string | undefined
45
+ readonly curated?: boolean | undefined
55
46
  }
56
47
 
57
48
  interface HeroStamp {
@@ -60,6 +51,8 @@ interface HeroStamp {
60
51
  readonly base: string
61
52
  readonly card: Readonly<Record<string, string>>
62
53
  readonly camera?: unknown
54
+ /** `"curated": true`: hand-picked art, re-stamped, never recaptured. */
55
+ readonly curated?: true
63
56
  }
64
57
 
65
58
  function sha256(bytes: Readonly<Uint8Array> | string): string {
@@ -242,16 +235,21 @@ async function heroState(shard: string): Promise<HeroState> {
242
235
  return { state: 'generated', content }
243
236
  }
244
237
  const stamp = await readStamp(shard)
238
+ const curated = field(stamp, 'curated') === true
245
239
  const stamped = field(stamp, 'content')
246
240
  if (typeof stamped !== 'string') {
247
- return { state: 'unstamped', content }
241
+ return { state: 'unstamped', content, curated }
248
242
  }
249
- const same = sameCard(field(stamp, 'card'), await cardHashes(shard))
250
243
  return {
251
- state: stamped === content && same ? 'fresh' : 'stale',
244
+ state:
245
+ stamped === content &&
246
+ sameCard(field(stamp, 'card'), await cardHashes(shard))
247
+ ? 'fresh'
248
+ : 'stale',
252
249
  content,
253
250
  stamped,
254
251
  captured: textOf(field(stamp, 'captured')),
252
+ curated,
255
253
  }
256
254
  }
257
255
 
@@ -262,12 +260,14 @@ async function writeHeroStamp(
262
260
  ): Promise<HeroStamp> {
263
261
  const previous = await readStamp(shard)
264
262
  const camera = options.camera ?? field(previous, 'camera')
263
+ const curated = field(previous, 'curated') === true
265
264
  const stamp: HeroStamp = {
266
265
  content: await heroContentHash(shard),
267
266
  captured: options.captured ?? new Date().toISOString(),
268
267
  base: options.base,
269
268
  card: await cardHashes(shard),
270
269
  ...(camera === undefined ? {} : { camera }),
270
+ ...(curated ? { curated: true } : {}),
271
271
  }
272
272
  const partial = path.join(shard, `${STAMP}.${randomUUID()}.partial`)
273
273
  try {