@wildshard/sdk 0.2.3 → 0.2.5
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 +178 -18
- package/bin/wildshard.mjs +1 -1
- package/codemods/0.2.5.mjs +12 -0
- package/lint/ratchet.json +1 -9
- package/lint/sdk-plugin.mjs +24 -2
- package/package.json +4 -3
- package/scripts/gen-format-schema.mjs +1 -1
- package/scripts/wildshard.mjs +8 -2
- package/skills/wildshard-upgrade/SKILL.md +15 -22
- package/src/cli/audio/audio.ts +17 -2
- package/src/cli/help.ts +11 -0
- package/src/cli/main.ts +1 -2
- package/src/cli/report.ts +8 -4
- package/src/cli/shardfile/command.ts +1 -2
- package/src/sharddev/agentFiles.ts +127 -0
- package/src/sharddev/author.ts +16 -3
- package/src/sharddev/bake/authoredWorld.ts +1 -1
- package/src/sharddev/bake/specimenCatalogue.ts +1 -1
- package/src/sharddev/bake/staticMaterials.ts +1 -1
- package/src/sharddev/check.ts +7 -6
- package/src/sharddev/checkProject.ts +4 -3
- package/src/sharddev/cli.ts +18 -5
- package/src/sharddev/formatJsonSchema.ts +1117 -3
- package/src/sharddev/kit/bakedGeometry.ts +58 -12
- package/src/sharddev/nativePopulationRows.ts +1 -1
- package/src/sharddev/newProject.ts +4 -25
- package/src/sharddev/performancePolicy.ts +16 -5
- package/src/sharddev/phasedBoss.ts +212 -34
- package/src/sharddev/project.ts +1 -1
- package/src/sharddev/projectEntryProof.ts +1 -1
- package/src/sharddev/projectGeneration.ts +1 -1
- package/src/sharddev/projectOutput.ts +1 -1
- package/src/sharddev/projectSections.ts +1 -1
- package/src/sharddev/refusals.ts +92 -18
- package/src/sharddev/reportCard.ts +1 -1
- package/src/sharddev/sections.ts +1 -1
- package/src/sharddev/species/clips.ts +64 -24
- package/src/sharddev/speciesBrains.ts +98 -15
- package/src/sharddev/updatePins.ts +254 -0
- package/src/sharddev/weapons/bowProfile.ts +3 -3
- package/src/sharddev/weapons/meleeProfile.ts +48 -4
- package/src/sharddev/worldScenes.ts +1 -1
- package/tsconfig.author.json +1 -0
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
// oxlint-disable-next-line import/no-nodejs-modules -- `new` and `update` own only a shard repo's agent files.
|
|
2
|
+
import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, symlinkSync, writeFileSync } from 'node:fs';
|
|
3
|
+
// oxlint-disable-next-line import/no-nodejs-modules -- Resolve files beneath the shard repo and the installed sdk.
|
|
4
|
+
import { dirname, resolve } from 'node:path';
|
|
5
|
+
|
|
6
|
+
// SHARD-AUTHORING SA28 (J314 Q7, Q8, Q27): the agent files of a shard repo. `new` and `update` both run
|
|
7
|
+
// `syncAgentFiles`: GUIDE.md and the four skills are the sdk's and are rewritten from the installed sdk; the
|
|
8
|
+
// `.agents/skills` links, AGENTS.md and CLAUDE.md are written when missing and otherwise left as the author keeps them.
|
|
9
|
+
|
|
10
|
+
/** The installed sdk's package root: GUIDE.md, `skills/` and package.json ship there (`files`). */
|
|
11
|
+
export const SDK_ROOT: string = resolve(import.meta.dirname, '../..');
|
|
12
|
+
|
|
13
|
+
/** SA13 (J314): the author's manual at the package root; `new` and `update` copy it into the repo. */
|
|
14
|
+
export const GUIDE_SOURCE: string = resolve(SDK_ROOT, 'GUIDE.md');
|
|
15
|
+
|
|
16
|
+
/** SA14, SA27 (J314 Q6): the core `wildshard` skill and its three siblings, at the package's `skills/`. */
|
|
17
|
+
export const SKILLS = ['wildshard', 'wildshard-mockup-to-model', 'wildshard-goldens', 'wildshard-upgrade'] as const;
|
|
18
|
+
export type SkillName = (typeof SKILLS)[number];
|
|
19
|
+
/** A skill's file in the installed sdk (or in `root`, another sdk). */
|
|
20
|
+
export const skillSource = (name: SkillName, root: string = SDK_ROOT): string => resolve(root, `skills/${name}/SKILL.md`);
|
|
21
|
+
/** Where a repo keeps a skill: Claude Code lists project skills from `.claude/skills/<name>/SKILL.md`. */
|
|
22
|
+
export const skillFile = (name: SkillName): string => `.claude/skills/${name}/SKILL.md`;
|
|
23
|
+
/** Codex lists project skills from `.agents/skills/<name>/`: a link to the Claude Code folder, so both read one copy. */
|
|
24
|
+
export const skillLink = (name: SkillName): string => `.agents/skills/${name}`;
|
|
25
|
+
/** The link's target, relative to `.agents/skills/`, so the repo keeps working wherever it is cloned. */
|
|
26
|
+
export const skillLinkTarget = (name: SkillName): string => `../../.claude/skills/${name}`;
|
|
27
|
+
/** The core `wildshard` skill (SA14). */
|
|
28
|
+
export const SKILL_SOURCE: string = skillSource('wildshard');
|
|
29
|
+
export const SKILL_FILE: string = skillFile('wildshard');
|
|
30
|
+
|
|
31
|
+
export const AGENTS_FILE = 'AGENTS.md';
|
|
32
|
+
export const CLAUDE_FILE = 'CLAUDE.md';
|
|
33
|
+
/** The repo's AGENTS.md as `new` writes it (Q8): read the guide first; the skills are in `.claude/skills/`. */
|
|
34
|
+
export const AGENTS_TEXT = `# AGENTS.md
|
|
35
|
+
|
|
36
|
+
This is a Wildshard shard repo: its shard source is at \`src/\`.
|
|
37
|
+
|
|
38
|
+
- Read \`GUIDE.md\` first. It is the author's manual: the loop, the shard source layout, budgets, and every refusal
|
|
39
|
+
with its fix.
|
|
40
|
+
- The skills are in \`.claude/skills/\`: \`wildshard\` (the loop, in order), \`wildshard-mockup-to-model\`,
|
|
41
|
+
\`wildshard-goldens\` and \`wildshard-upgrade\`. \`.agents/skills/\` links to the same folders, for Codex.
|
|
42
|
+
- \`wildshard update\` rewrites \`GUIDE.md\` and those four skills from the installed sdk, so never edit them here.
|
|
43
|
+
It leaves this file alone once you change it: add your own rules below.
|
|
44
|
+
`;
|
|
45
|
+
/** Claude Code reads CLAUDE.md; it imports AGENTS.md so both agents read one file. */
|
|
46
|
+
export const CLAUDE_TEXT = '@AGENTS.md\n';
|
|
47
|
+
/** Every AGENTS.md text an earlier sdk wrote. `update` replaces an untouched copy of one of these and leaves any other
|
|
48
|
+
* text, which the author wrote. When AGENTS_TEXT changes, add the old text here. */
|
|
49
|
+
const PAST_AGENTS_TEXTS: readonly string[] = [];
|
|
50
|
+
|
|
51
|
+
/** What `syncAgentFiles` did to one file. `left` is a file the author changed, kept as it is. */
|
|
52
|
+
export type AgentFileAction = 'added' | 'updated' | 'unchanged' | 'left';
|
|
53
|
+
export interface AgentFileChange { readonly file: string; readonly action: AgentFileAction }
|
|
54
|
+
|
|
55
|
+
/** Write `text` to `file` unless it already holds it; the sdk's files are always the sdk's. */
|
|
56
|
+
function writeOwned(project: string, file: string, text: Buffer): AgentFileAction {
|
|
57
|
+
const path = resolve(project, file);
|
|
58
|
+
if (!existsSync(path)) { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, text); return 'added'; }
|
|
59
|
+
if (readFileSync(path).equals(text)) return 'unchanged';
|
|
60
|
+
writeFileSync(path, text);
|
|
61
|
+
return 'updated';
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** Write `text` to `file` only when it is missing, or still one of the sdk's own `past` texts. */
|
|
65
|
+
function writeAuthored(project: string, file: string, text: string, past: readonly string[]): AgentFileAction {
|
|
66
|
+
const path = resolve(project, file);
|
|
67
|
+
if (!existsSync(path)) { writeFileSync(path, text); return 'added'; }
|
|
68
|
+
const now = readFileSync(path, 'utf8');
|
|
69
|
+
if (now === text) return 'unchanged';
|
|
70
|
+
if (!past.includes(now)) return 'left';
|
|
71
|
+
writeFileSync(path, text);
|
|
72
|
+
return 'updated';
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** Link `.agents/skills/<name>` to the Claude Code skill folder, unless something of the author's is there. */
|
|
76
|
+
function writeLink(project: string, name: SkillName): AgentFileAction {
|
|
77
|
+
const path = resolve(project, skillLink(name)), target = skillLinkTarget(name);
|
|
78
|
+
let stat;
|
|
79
|
+
try { stat = lstatSync(path); } catch { stat = undefined; }
|
|
80
|
+
if (stat === undefined) { mkdirSync(dirname(path), { recursive: true }); symlinkSync(target, path, 'dir'); return 'added'; }
|
|
81
|
+
return stat.isSymbolicLink() && readlinkSync(path) === target ? 'unchanged' : 'left';
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* SA28: `new` and `update`. Rewrite GUIDE.md and the four skills from the sdk at `root` (the installed one), and write
|
|
86
|
+
* the `.agents/skills` links, AGENTS.md and CLAUDE.md when missing. Touches nothing else: a file whose bytes already
|
|
87
|
+
* match is not rewritten, and an AGENTS.md, CLAUDE.md or link the author changed is left as it is.
|
|
88
|
+
*/
|
|
89
|
+
export function syncAgentFiles(project: string, root: string = SDK_ROOT, pastAgentsTexts: readonly string[] = PAST_AGENTS_TEXTS): readonly AgentFileChange[] {
|
|
90
|
+
const changes: AgentFileChange[] = [{ file: 'GUIDE.md', action: writeOwned(project, 'GUIDE.md', readFileSync(resolve(root, 'GUIDE.md'))) }];
|
|
91
|
+
for (const name of SKILLS) changes.push({ file: skillFile(name), action: writeOwned(project, skillFile(name), readFileSync(skillSource(name, root))) });
|
|
92
|
+
for (const name of SKILLS) changes.push({ file: skillLink(name), action: writeLink(project, name) });
|
|
93
|
+
changes.push({ file: AGENTS_FILE, action: writeAuthored(project, AGENTS_FILE, AGENTS_TEXT, pastAgentsTexts) });
|
|
94
|
+
changes.push({ file: CLAUDE_FILE, action: writeAuthored(project, CLAUDE_FILE, CLAUDE_TEXT, []) });
|
|
95
|
+
return changes;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/** The sdk version at `root`, for update's first line. */
|
|
99
|
+
function sdkVersion(root: string): string {
|
|
100
|
+
const parsed: unknown = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8'));
|
|
101
|
+
return typeof parsed === 'object' && parsed !== null && 'version' in parsed && typeof parsed.version === 'string' ? parsed.version : 'unknown';
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/** A shard repo is a folder whose package.json lists `@wildshard/sdk` (`new` writes it; a blender repo as a dev dependency). */
|
|
105
|
+
export function assertShardRepo(project: string): void {
|
|
106
|
+
const file = resolve(project, 'package.json');
|
|
107
|
+
let parsed: unknown;
|
|
108
|
+
try { parsed = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : undefined; }
|
|
109
|
+
catch (error) { throw new Error(`update: ${project} is not a shard repo: its package.json is not valid JSON (${error instanceof Error ? error.message : String(error)})`, { cause: error }); }
|
|
110
|
+
const fields: unknown[] = typeof parsed === 'object' && parsed !== null
|
|
111
|
+
? [Reflect.get(parsed, 'dependencies'), Reflect.get(parsed, 'devDependencies')] : [];
|
|
112
|
+
if (!fields.some(field => typeof field === 'object' && field !== null && Object.hasOwn(field, '@wildshard/sdk'))) throw new Error(`update: ${project} is not a shard repo: its package.json does not list @wildshard/sdk (or it has none)`);
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/** `wildshard update [dir]`: sync the agent files of the shard repo at `project`, and say what changed, one line each. */
|
|
116
|
+
export function updateShardRepo(project: string, root: string = SDK_ROOT): string[] {
|
|
117
|
+
assertShardRepo(project);
|
|
118
|
+
const changes = syncAgentFiles(project, root);
|
|
119
|
+
const lines = [`wildshard update: GUIDE.md and the skills from @wildshard/sdk ${sdkVersion(root)}`];
|
|
120
|
+
for (const { file, action } of changes) {
|
|
121
|
+
if (action === 'left') lines.push(` left ${file}: you changed it, so update kept yours`);
|
|
122
|
+
else if (action !== 'unchanged') lines.push(` ${action} ${file}`);
|
|
123
|
+
}
|
|
124
|
+
const touched = changes.filter(change => change.action === 'added' || change.action === 'updated').length;
|
|
125
|
+
lines.push(touched === 0 ? ' already up to date' : ` ${String(touched)} file${touched === 1 ? '' : 's'} written; nothing else touched`);
|
|
126
|
+
return lines;
|
|
127
|
+
}
|
package/src/sharddev/author.ts
CHANGED
|
@@ -1,3 +1,16 @@
|
|
|
1
|
-
//
|
|
2
|
-
//
|
|
3
|
-
|
|
1
|
+
// The SDK's starting shardfile (SHARD-AUTHORING SA26): built here and admitted by shard-format's own parser, the one
|
|
2
|
+
// the client runs, so a project starts from a file the game accepts.
|
|
3
|
+
import { parseShardfile, type Shardfile } from '@wildshard/format/shardSchema';
|
|
4
|
+
import { ENTRY_WIDTH } from '@wildshard/format/contentBounds';
|
|
5
|
+
import { SHARDFILE_VERSION } from '@wildshard/format/version';
|
|
6
|
+
|
|
7
|
+
/** Start an author project with a valid empty world; add baked content before shipping a playable shard. */
|
|
8
|
+
export function emptyShardfile(identity: Shardfile['identity']): Shardfile {
|
|
9
|
+
const edge = { heights: Array.from({ length: 257 }, () => 0), colours: Array.from({ length: 257 }, () => [0.5, 0.5, 0.5]), roadHeight: 0 };
|
|
10
|
+
return parseShardfile({ version: SHARDFILE_VERSION, identity, accent: 'sand', requires: { sdk: SHARDFILE_VERSION, capabilities: [], commons: [], commonsWire: {}, commonsCosts: {} }, budgets: { library: { resident: 0, compressed: 0 }, sim: { resident: 0, compressed: 0 }, overlap: 0 },
|
|
11
|
+
entryways: [{ edge: 'north', at: [0, 0, 250], width: ENTRY_WIDTH }, { edge: 'east', at: [250, 0, 0], width: ENTRY_WIDTH }, { edge: 'south', at: [0, 0, -250], width: ENTRY_WIDTH }, { edge: 'west', at: [-250, 0, 0], width: ENTRY_WIDTH }],
|
|
12
|
+
look: { families: [], grade: { exposure: 0, saturation: 1, contrast: 1, lut: null }, clock: 'engine', dayOverride: null, keys: [] },
|
|
13
|
+
sim: { fixedHz: 60, scriptTickDivisor: 2, commandVersion: 0, snapshotVersion: 0, scripts: [] },
|
|
14
|
+
state: { version: 1, sharedOwner: 'host', playerKey: 'actorId', shared: [], player: [] }, authorCaps: { players: 32, speed: 15 },
|
|
15
|
+
serverBudget: { tickMicros: 1000, memory: 1_000_000, entities: 100, commandsPerTick: 32 }, edge: { north: edge, south: edge, east: edge, west: edge }, files: [], tiles: [], library: [], critical: [], far: null });
|
|
16
|
+
}
|
|
@@ -3,7 +3,7 @@ import * as v from 'valibot';
|
|
|
3
3
|
import { isJsonData } from '@wildshard/format/json';
|
|
4
4
|
import { FAMILY_IDS, PbrMaterialSchema } from '@wildshard/format/materialFamilies';
|
|
5
5
|
import { MaterialsSchema, materialGraphIr } from '@wildshard/format/materials';
|
|
6
|
-
import { parseShardfile, type Shardfile } from '@wildshard/
|
|
6
|
+
import { parseShardfile, type Shardfile } from '@wildshard/format/shardSchema';
|
|
7
7
|
import { normalizeWorldGlb, type NormalizedWorld, type WorldPrimitive } from './world';
|
|
8
8
|
import { parseWorldSource } from '../worldSource';
|
|
9
9
|
import { bakeWorldTexture } from './textureWasm';
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { parse, object, array, string, unknown } from 'valibot';
|
|
2
2
|
import { PickupCatalogueSchema, SpecimenBookSchema, type PickupCatalogueRows, type SpecimenBookRows, type SpecimenModelMetadataRows } from '@wildshard/format/specimenCatalogue';
|
|
3
3
|
import pickupRows from '@wildshard/engine/game/data/pickupCatalogue' with { type: 'json' };
|
|
4
|
-
import { namedJsonSchema } from '
|
|
4
|
+
import { namedJsonSchema } from '../formatJsonSchema';
|
|
5
5
|
import { encodeCanonicalJson } from '../immutable';
|
|
6
6
|
import { nameBlob, type NamedBlob, type BlobOptions } from '../blobs';
|
|
7
7
|
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { MeshStandardMaterial, type BufferGeometry } from 'three';
|
|
2
|
-
import type { Shardfile } from '@wildshard/
|
|
2
|
+
import type { Shardfile } from '@wildshard/format/shardSchema';
|
|
3
3
|
import { parseKtx2 } from '../assets';
|
|
4
4
|
import { hashImmutableBytes } from '../immutable';
|
|
5
5
|
import type { WorldMaterial, WorldTexture } from './world';
|
package/src/sharddev/check.ts
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
// SA21: every refusal carries a rule id, a one-line fix and a GUIDE.md link, from refusals.ts.
|
|
4
4
|
import { diagnosticNow } from '@wildshard/engine/core/clock';
|
|
5
5
|
import { authorErrorText } from './authorError';
|
|
6
|
-
import { refusalHint, refusalNote, type RefusalStep } from './refusals';
|
|
6
|
+
import { refusalCode, refusalHint, refusalNote, type RefusalStep } from './refusals';
|
|
7
7
|
|
|
8
8
|
/** The five steps, in the order they run. */
|
|
9
9
|
export type CheckStepName = 'lint' | 'build' | 'validate' | 'prove' | 'report';
|
|
@@ -19,8 +19,9 @@ export interface CheckRefusal {
|
|
|
19
19
|
readonly guide: string;
|
|
20
20
|
readonly file?: string;
|
|
21
21
|
}
|
|
22
|
-
/** A refusal as a step reports it: a lint diagnostic brings oxlint's code and help
|
|
23
|
-
|
|
22
|
+
/** A refusal as a step reports it: a lint diagnostic brings oxlint's code and help, a shard-format refusal its stable
|
|
23
|
+
* code (SA41); refusals.ts fills in the rest. */
|
|
24
|
+
export interface StepRefusal { readonly message: string; readonly lint?: { readonly code: string | null; readonly help: string | null }; readonly code?: string | undefined; readonly file?: string; readonly as?: RefusalStep }
|
|
24
25
|
/** A warning: the same fields as a refusal, but it does not fail the verdict (an unprepared draft, J198). */
|
|
25
26
|
export type CheckWarning = CheckRefusal;
|
|
26
27
|
/** One step's result and wall-clock duration in milliseconds. */
|
|
@@ -53,15 +54,15 @@ const NEEDS_BUILD = new Set<CheckStepName>(['validate', 'prove', 'report']);
|
|
|
53
54
|
|
|
54
55
|
async function outcomeOf(work: () => Promise<StepOutcome>): Promise<StepOutcome> {
|
|
55
56
|
try { return await work(); }
|
|
56
|
-
catch (error) { return { status: 'fail', refusals: [{ message: authorErrorText(error) }] }; }
|
|
57
|
+
catch (error) { return { status: 'fail', refusals: [{ message: authorErrorText(error), code: refusalCode(error) }] }; }
|
|
57
58
|
}
|
|
58
59
|
|
|
59
60
|
/** Run every step in order, timing each, and give the verdict. `output` is read after the build; `now` is for tests. */
|
|
60
61
|
export async function runCheck(project: string, output: () => string | null, steps: CheckSteps, now: () => number = diagnosticNow): Promise<CheckResult> {
|
|
61
62
|
const started = now(), rows: CheckStep[] = [], refusals: CheckRefusal[] = [], warnings: CheckWarning[] = [];
|
|
62
|
-
const named = (step: CheckStepName, { message, lint, file, as }: StepRefusal): CheckRefusal => {
|
|
63
|
+
const named = (step: CheckStepName, { message, lint, code, file, as }: StepRefusal): CheckRefusal => {
|
|
63
64
|
// SA3: build's shard file step names its rules by its own step (a format refusal is not a source one).
|
|
64
|
-
const { rule, fix, guide } = refusalNote(as ?? step, message, lint);
|
|
65
|
+
const { rule, fix, guide } = refusalNote(as ?? step, message, { lint, code });
|
|
65
66
|
return { step, rule, message, fix, guide, ...(file === undefined ? {} : { file }) };
|
|
66
67
|
};
|
|
67
68
|
let built = true;
|
|
@@ -10,7 +10,7 @@ import { basename, dirname, resolve } from 'node:path';
|
|
|
10
10
|
import * as v from 'valibot';
|
|
11
11
|
import { AuthorProofPlanSchema } from '@wildshard/engine/host/tickProtocol';
|
|
12
12
|
import { measureSimulation, proveAuthorSimulation } from '@wildshard/engine/host/headless';
|
|
13
|
-
import type { Shardfile } from '@wildshard/
|
|
13
|
+
import type { Shardfile } from '@wildshard/format/shardSchema';
|
|
14
14
|
import { buildProject } from './project';
|
|
15
15
|
import { isHandwrittenSource, isRepoSource, shardOutputRoot } from './shardSource';
|
|
16
16
|
import { handwrittenIdentity, settleHandwritten } from './handwritten';
|
|
@@ -19,6 +19,7 @@ import { performanceReport, type PerformanceObservations } from './reportCard';
|
|
|
19
19
|
import { lintOutcome, runCheck, type CheckResult, type StepOutcome } from './check';
|
|
20
20
|
import type { ProjectManifestSource } from './projectManifest';
|
|
21
21
|
import { authorErrorText } from './authorError';
|
|
22
|
+
import { refusalCode } from './refusals';
|
|
22
23
|
import { DRAFT_SDK, draftMessage } from './draft';
|
|
23
24
|
|
|
24
25
|
/** The author proof tape `check` runs when the project has one (format: `AuthorProofPlanSchema`). */
|
|
@@ -96,7 +97,7 @@ export async function checkProject(projectPath: string, outputPath: string | und
|
|
|
96
97
|
let file: string | undefined;
|
|
97
98
|
// The draft warning goes in the verdict (below), so the writer leaves it out.
|
|
98
99
|
try { file = await options.writeShardfile?.(output, project, { draftWarning: false }); }
|
|
99
|
-
catch (error) { return { status: 'fail', refusals: [{ message: authorErrorText(error), as: 'shardfile' }] }; }
|
|
100
|
+
catch (error) { return { status: 'fail', refusals: [{ message: authorErrorText(error), code: refusalCode(error), as: 'shardfile' }] }; }
|
|
100
101
|
const warnings = isDraft(output) ? [{ message: draftMessage(shard.identity.slug), as: 'shardfile' as const }] : [];
|
|
101
102
|
return { status: 'pass', note: `built ${shard.identity.slug} v${shard.version}${file === undefined ? '' : `, ${file}`}`, warnings };
|
|
102
103
|
},
|
|
@@ -120,7 +121,7 @@ export async function checkProject(projectPath: string, outputPath: string | und
|
|
|
120
121
|
const warnings = card.issues.length - refused.length;
|
|
121
122
|
const note = `${(card.download.total / 1024 / 1024).toFixed(2)} MB download, ~${card.estimatedPlayable.seconds.toFixed(1)} s to playable, ${warnings} warning${warnings === 1 ? '' : 's'}`;
|
|
122
123
|
return await Promise.resolve({ status: card.pass ? 'pass' : 'fail', note,
|
|
123
|
-
refusals: refused.map(issue => ({ message: `${issue.metric}: ${String(issue.actual)} over ${String(issue.limit)}
|
|
124
|
+
refusals: refused.map(issue => ({ message: `${issue.metric}: ${String(issue.actual)} over ${String(issue.limit)}`, code: issue.code })) });
|
|
124
125
|
},
|
|
125
126
|
});
|
|
126
127
|
}
|
package/src/sharddev/cli.ts
CHANGED
|
@@ -3,7 +3,7 @@ import { basename, dirname, resolve } from 'node:path';
|
|
|
3
3
|
// oxlint-disable-next-line import/no-nodejs-modules -- `prove` tells a project from a built product by its config file.
|
|
4
4
|
import { existsSync } from 'node:fs';
|
|
5
5
|
import { buildProject, readProjectAssets, validateProject } from './project';
|
|
6
|
-
import { ShardfileSchema, type Shardfile } from '@wildshard/
|
|
6
|
+
import { ShardfileSchema, type Shardfile } from '@wildshard/format/shardSchema';
|
|
7
7
|
import { devProject } from './dev';
|
|
8
8
|
import { proveAuthorSimulation, measureSimulation, validateSimulation } from '@wildshard/engine/host/headless';
|
|
9
9
|
import { performanceReport, performanceReportLines, type PerformanceObservations } from './reportCard';
|
|
@@ -15,16 +15,18 @@ import { assetOverdraw } from './assets';
|
|
|
15
15
|
import process from 'node:process';
|
|
16
16
|
import { buildBehaviourProject } from './buildBehaviour';
|
|
17
17
|
import { synthProject } from './synth';
|
|
18
|
-
import { formatJsonSchemas, schemaAt, schemaDeclaration } from '
|
|
18
|
+
import { formatJsonSchemas, schemaAt, schemaDeclaration } from './formatJsonSchema';
|
|
19
19
|
import { decisionModuleContracts } from '@wildshard/format/scriptContract';
|
|
20
20
|
import { outputScriptAdmissionRows, validateOutputProduct } from './outputProduct';
|
|
21
21
|
import { locatedError } from './authorError';
|
|
22
22
|
import type { ProjectManifestSource } from './projectManifest';
|
|
23
23
|
import { templateNamed, writeShardRepo } from './newProject';
|
|
24
|
+
import { updateShardRepo } from './agentFiles';
|
|
25
|
+
import { updatePins } from './updatePins';
|
|
24
26
|
import { findShardSource, isHandwrittenSource, isRepoSource, shardOutputRoot } from './shardSource';
|
|
25
27
|
import { checkProject, readProofTape } from './checkProject';
|
|
26
28
|
import { checkLines } from './check';
|
|
27
|
-
import { refusalHint, refusalNote, type RefusalStep } from './refusals';
|
|
29
|
+
import { refusalCode, refusalHint, refusalNote, type RefusalStep } from './refusals';
|
|
28
30
|
|
|
29
31
|
const unmeasured: PerformanceObservations = { scripts: { p95Micros: 0, maxMicros: 0, samples: 0 }, fuel: { p95: 0, max: 0, samples: 0 } };
|
|
30
32
|
function printReport(shard: Shardfile, observed: PerformanceObservations, policy: 'warn' | 'refuse'): void {
|
|
@@ -80,6 +82,17 @@ async function runCommand(given: readonly string[], options: CliOptions): Promis
|
|
|
80
82
|
if (result.verdict === 'fail') process.exitCode = 1;
|
|
81
83
|
return;
|
|
82
84
|
}
|
|
85
|
+
if (command === 'update') {
|
|
86
|
+
// SA28 (J314 Q7, Q27): one verb. SA18: `--pins[=<version>]` also moves the pins, installs, applies the release's
|
|
87
|
+
// codemods and runs check (updatePins.ts); with no version it takes npm's latest.
|
|
88
|
+
const rest = args.slice(1), pins = rest.filter(value => value === '--pins' || value.startsWith('--pins='));
|
|
89
|
+
const positional = rest.filter(value => !pins.includes(value)), version = pins[0]?.startsWith('--pins=') === true ? pins[0].slice('--pins='.length) : 'latest';
|
|
90
|
+
if (pins.length > 1 || version === '' || positional.length > 1 || positional.some(value => value.startsWith('-'))) throw new Error('usage: wildshard update [dir] [--pins[=<version>]]');
|
|
91
|
+
if (pins.length === 1 && /^\d+\.\d+\.\d+/u.test(positional[0] ?? '') && !existsSync(resolve(positional[0] ?? ''))) throw new Error(`usage: wildshard update [dir] [--pins[=<version>]]: name a version as --pins=${positional[0] ?? ''}`);
|
|
92
|
+
if (pins.length === 1) { await updatePins(resolve(positional[0] ?? '.'), version); return; }
|
|
93
|
+
for (const line of updateShardRepo(resolve(positional[0] ?? '.'))) console.info(line);
|
|
94
|
+
return;
|
|
95
|
+
}
|
|
83
96
|
if (input === undefined) throw new Error('usage: wildshard new <dir> | check <source> [folder] [--json] | synth <source> | build <source> [folder] [--shardfile-only|--folder-only] [--no-placeholders] [--output=<slug>] | build <source> --behaviour-only | validate <source|shard.json> | dev <source> [port] (wildshard --help lists them all)');
|
|
84
97
|
// SA16 (J314): a hand-written src/ (--template blender) has no shard.config.ts to build, synth or serve; check settles it.
|
|
85
98
|
if ((command === 'build' || command === 'synth' || command === 'dev') && isRepoSource(resolve(input)) && isHandwrittenSource(resolve(input))) throw new Error(`${command}: ${input} is a hand-written shard file (--template blender): run wildshard check on the repo, which settles and builds it`);
|
|
@@ -176,13 +189,13 @@ async function runCommand(given: readonly string[], options: CliOptions): Promis
|
|
|
176
189
|
throw new Error('unknown wildshard command');
|
|
177
190
|
}
|
|
178
191
|
/** The step a verb's refusal comes from (SA21): `dev` and `synth` build. */
|
|
179
|
-
const STEPS: Readonly<Record<string, RefusalStep>> = { new: 'new', validate: 'validate', prove: 'prove' };
|
|
192
|
+
const STEPS: Readonly<Record<string, RefusalStep>> = { new: 'new', update: 'update', validate: 'validate', prove: 'prove' };
|
|
180
193
|
/** The refusal with its rule, fix and GUIDE.md link on a second line; the first line stays the refusing code's words. */
|
|
181
194
|
function authorRefusal(command: string | undefined, error: unknown): unknown {
|
|
182
195
|
const located = locatedError(error);
|
|
183
196
|
const message = located instanceof Error ? located.message : String(located);
|
|
184
197
|
const step = error instanceof ShardfileRefusalError ? 'shardfile' : command !== undefined && Object.hasOwn(STEPS, command) ? STEPS[command] : undefined;
|
|
185
|
-
const hint = refusalHint(refusalNote(step ?? 'build', message));
|
|
198
|
+
const hint = refusalHint(refusalNote(step ?? 'build', message, { code: refusalCode(error) }));
|
|
186
199
|
return new Error(`${message}\n ${hint}`, { cause: error });
|
|
187
200
|
}
|
|
188
201
|
/** Run the author CLI; returns only after validation/build completes. */
|