spine-rigc 2.11.1 → 2.12.0

package/src/cli/repack.ts

@@ -0,0 +1,408 @@
+/**
+ * `rigc repack <build> --out <dir>` — a packed build repacked from its own
+ * output, written only after the repack is shown to have lost nothing (issue
+ * #1169).
+ *
+ * A consumer that keeps only `skeleton.json`, `skeleton.atlas` and the page
+ * PNGs could not take up a packer improvement (`--page-edges free`,
+ * `--pack-shape polygon`) without regenerating its parts upstream. The route
+ * it measured by hand — cut each region off its page, `ingest --art loose`,
+ * `build --pack` over the cut parts — is this command, in process and through
+ * the tree's own functions: `liftAtlas` (`extractRegion` per region), `ingest`,
+ * and `runBuild` with the entry's own gate, the body every `build` runs.
+ *
+ * 🔒 **Nothing reaches `--out` until three things have been shown**, and the
+ * command prints each:
+ *
+ *   (a) every region lifted off the NEW pages is pixel-identical, by name, to
+ *       the same region lifted off the input's pages (`regionDifferences`);
+ *   (b) the rebuilt `skeleton.json` is byte-identical to the input's. A repack
+ *       is entitled to change nothing in the skeleton: attachments name their
+ *       regions and the atlas alone carries where a region sits, so the pack
+ *       owns the atlas and the pages and none of the skeleton. Measured on the
+ *       tree's recipes, every repack of a rigc build wrote the same bytes;
+ *       a difference is refused naming the paths (`skeletonDifferences`);
+ *   (c) the gate is green — `runBuild` returns only then, having gated the
+ *       compile and the packed pair exactly as `build --pack` does.
+ *
+ * The build runs in a work directory of its own under `tmpdir()`
+ * (`REPACK_WORK_PREFIX`), which also holds the lifted parts and the two specs;
+ * the output is the build alone, the same four kinds of file `build --pack`
+ * writes, so a repacked build can be repacked again. The directory is removed
+ * when the command ends — green, refused, a gate that exits, or a throw —
+ * from this function's `finally` and, for the `process.exit` inside
+ * `runBuild` that no `finally` sees, from an `exit` listener. A process killed
+ * by a signal runs neither and leaves its one directory.
+ *
+ * ⚠️ The lifted parts are not kept: the output is the input's shape, and the
+ * parts are recoverable from it at any time by the same lift — keeping a
+ * second copy of every texel beside the pages would be two records of one
+ * thing that can disagree.
+ */
+import { parseAtlasText } from '../atlas.ts';
+import { relativeImagesPath } from '../compile.ts';
+import { ingest, INGEST_GUTTERS, IngestError, type IngestFinding, type IngestOptions, IngestSpecRefused, type IngestStage } from '../ingest.ts';
+import { MODEL_DOCUMENT_FILE } from '../model.ts';
+import { atlasRefusals, documentDisagreements, firstLineApart, type InputPage, liftAtlas, polygonOwnedTexels, regionDifferences, REPACK_WORK_PREFIX, RepackError, skeletonDifferences } from '../repack.ts';
+import {
+  type BuildGate,
+  type CommandArgs,
+  documentStageBeside,
+  modelTextBeside,
+  parseJsonNamed,
+  readIntFlag,
+  readPackShape,
+  readPageEdges,
+  readProfile,
+  readSkeletonText,
+  readVersion,
+  resolveBuild,
+  runBuild,
+  UsageError,
+} from './shared.ts';
+import { DEFAULT_PADDING, DEFAULT_PAGE_SIZE } from '../atlas.ts';
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+
+/** The flags `repack` takes: the packing flags `build --pack` takes, the gate's profile, the atlas when it is not beside the skeleton, the stage `ingest` takes, and `--out`. */
+/**
+ * The switch that writes a rebuild whose skeleton differs from the input's
+ * (issue #1169's follow-up). Default off: check (b) refuses a difference, and
+ * the refusal names this flag. A general acceptance rather than a switch for one
+ * field, because the command cannot know WHY a skeleton differs — only where —
+ * and every path is printed when it is accepted.
+ */
+export const ACCEPT_FLAG = 'accept-skeleton-differences';
+
+export const REPACK_FLAGS = ['out', 'atlas', 'page-size', 'padding', 'page-edges', 'pack-shape', 'profile', 'stage', 'stage-box', ACCEPT_FLAG] as const;
+
+/** `build`'s flags that `repack` does not take, and why — each refused by name rather than ignored. */
+const BUILD_FLAGS_REFUSED: Readonly<Record<string, string>> = {
+  rig: 'repack reads the rig back out of the skeleton (ingest); it takes no rig spec',
+  motion: 'repack reads the motion back out of the skeleton (ingest); it takes no motion spec',
+  manifest: 'repack lifts the parts off the pages; it takes no cut manifest',
+  images: 'repack lifts the parts off the pages the atlas names; it takes no parts directory',
+  'copy-images': 'repack always writes self-contained pages into --out, which is what packing is',
+  pack: 'repack always packs; the flag would say nothing',
+  'atlas-in': 'repack MAKES a new pack out of the regions of the old one; --atlas-in would keep the old pack — pass the build itself',
+  cut: 'repack takes a build directory, not a cut',
+  cuts: 'repack takes a build directory, not a cuts table',
+};
+
+/** The three files besides the pages that every repacked build is, in the order `runBuild` writes them. */
+const BUILD_TEXTS = ['skeleton.json', 'skeleton.atlas', MODEL_DOCUMENT_FILE] as const;
+
+/**
+ * A hook between the lift and the build, given the directory the parts were
+ * lifted into — the selftest's plant (`RPK`), which alters a lifted part to
+ * show check (a) refusing before anything is written. Nothing else passes one.
+ */
+export type RepackPlant = (liftDir: string) => void;
+
+/** How every gate's closing line opens (`BuildGate.look`), which a staged build drops. */
+const LOOK_LINE = 'rigc: look at it: ';
+
+/** How many skeleton differences a refusal lists before it says how many more there are. */
+const SKELETON_DIFFERENCES_SHOWN = 8;
+
+/** `--stage x,y,w,h`, read as `ingest` reads it. */
+function readStageFlag(raw: string | undefined): IngestStage | undefined {
+  if (raw === undefined) return undefined;
+  const parts = raw.split(',').map(Number);
+  if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) throw new UsageError(`--stage is ${JSON.stringify(raw)}; give four numbers, x,y,width,height`);
+  return { x: parts[0], y: parts[1], width: parts[2], height: parts[3] };
+}
+
+/** Every flag given that `repack` does not take, refused by name. */
+function refuseForeignFlags(flags: Record<string, string>): void {
+  const taken = new Set<string>([...REPACK_FLAGS, 'help']);
+  for (const name of Object.keys(flags).sort()) {
+    if (taken.has(name)) continue;
+    const why = BUILD_FLAGS_REFUSED[name];
+    throw new UsageError(why === undefined ? `repack takes no --${name}; it takes --${REPACK_FLAGS.join(', --')}` : `repack takes no --${name}: ${why}`);
+  }
+}
+
+/** `--out`: required, and absent or an empty directory — refused by name otherwise, before anything is read. */
+function readOut(flags: Record<string, string>): string {
+  if (flags.out === undefined) throw new UsageError('repack needs --out <dir> — the directory the repacked build is written into');
+  const out = resolve(flags.out);
+  if (existsSync(out)) {
+    if (!statSync(out).isDirectory()) throw new RepackError(`--out ${out} is a file; it takes a directory, absent or empty — nothing was written`, 2);
+    const held = readdirSync(out).sort();
+    if (held.length > 0) {
+      throw new RepackError(
+        `--out ${out} is not empty (${held.slice(0, 4).join(', ')}${held.length > 4 ? `, … ${held.length} entries` : ''}) — a page an earlier pack wrote and this one does not ` +
+          'would stay beside the new atlas with nothing naming it, so repack writes only into an absent or empty directory; nothing was written',
+        2,
+      );
+    }
+  }
+  return out;
+}
+
+/**
+ * The one place `repack` calls `ingest`'s options: the skeleton read back with
+ * `--art loose` (an `image` per attachment, named after the region it draws,
+ * which is the file the lift wrote), the parts directory spelled from the
+ * specs, and the stage by `ingest`'s own rules — a caller's `--stage`, else
+ * the model document beside the skeleton when it is this skeleton's, else the
+ * header. A new `ingest` option goes in here and nowhere else.
+ */
+function ingestOptionsFor(
+  skeletonPath: string,
+  specsDir: string,
+  liftDir: string,
+  stage: IngestStage | undefined,
+  stageBox: string | undefined,
+  documentStage: IngestStage | null | undefined,
+): IngestOptions {
+  return {
+    ...(stageBox === undefined ? {} : { stageBox }),
+    ...(documentStage === undefined ? {} : { documentStage }),
+    name: basename(skeletonPath, '.json'),
+    art: 'loose',
+    images: relativeImagesPath(specsDir, liftDir),
+    stage,
+    source: basename(skeletonPath),
+    version: readVersion(),
+  };
+}
+
+/** The stage line: the box the rebuild declares and where it came from (issue #1169's step 6). */
+function stageLine(
+  rig: { skeleton?: { x?: number | null; y?: number | null; width?: number | null; height?: number | null } },
+  flagged: boolean,
+  stageBox: string | undefined,
+  documentStage: IngestStage | null | undefined,
+): string {
+  const head = rig.skeleton;
+  const box =
+    head !== undefined && typeof head.width === 'number' && typeof head.height === 'number'
+      ? `${head.width} x ${head.height} at ${head.x ?? 0},${head.y ?? 0}`
+      : 'none';
+  const why = flagged
+    ? '— from --stage, which ingest takes only for a skeleton that states no box'
+    : stageBox !== undefined
+      ? `— read from the bounding box in slot "${stageBox}" (--stage-box), the stage the build carried in its own files${documentStage === undefined ? '' : `, and equal to the ${MODEL_DOCUMENT_FILE} beside it (ingest refuses the two disagreeing)`}`
+      : documentStage !== undefined
+      ? `— read from the ${MODEL_DOCUMENT_FILE} beside it (its spine.sha256 is this skeleton's)${documentStage === null ? ', which states the rig declared none' : ''}`
+      : box === 'none'
+        ? `— the skeleton's header states no box and no ${MODEL_DOCUMENT_FILE} of this skeleton is beside it`
+        : `— read from the skeleton's header box: no ${MODEL_DOCUMENT_FILE} of this skeleton is beside it, and which box it is depends on the rigc that wrote it — on a build written before 2.2.0 it is the stage itself, on one written since it is the setup-pose bounding box, not the stage the rig declared, and nothing in the skeleton says which; keep ${MODEL_DOCUMENT_FILE} beside the pair to carry the stage, or, for a build that carries it as a bounding box (skeleton.stageBox), pass --stage-box <slot> to read it exactly`;
+  return `  ..    stage  ${box} ${why}. skeleton.json is held byte-identical below whatever it is; ${MODEL_DOCUMENT_FILE}'s stage, and the stage rules on the rebuild, read it`;
+}
+
+/** The findings `ingest` reported, in its own format, blockers first. */
+function findingLines(findings: readonly IngestFinding[]): string[] {
+  const width = Math.max(...Object.values(INGEST_GUTTERS).map((gutter) => gutter.length));
+  const lines: string[] = [];
+  for (const kind of ['blocker', 'judgement', 'lossy'] as const) {
+    for (const f of findings.filter((x) => x.kind === kind)) lines.push(`  ${INGEST_GUTTERS[kind].padEnd(width)} ${f.code}: ${f.where} — ${f.detail}`);
+  }
+  return lines;
+}
+
+/**
+ * `runBuild` with its two closing lines restated for a build that is staged:
+ * `rigc: wrote <work>/…` becomes `staged <work>/…`, and the `look at it` line
+ * is dropped — the work directory is removed when the command ends, and
+ * `repack` names `--out` itself once it has written there. Every other line is
+ * printed as it comes, so a gate that exits mid-way loses none.
+ */
+function stagedBuild(flags: Record<string, string>, gate: BuildGate): void {
+  const print = console.log;
+  console.log = (...args: unknown[]): void => {
+    const line = args.map((a) => (typeof a === 'string' ? a : String(a))).join(' ');
+    if (line.startsWith('rigc: wrote ')) print(`  ..    staged ${line.slice('rigc: wrote '.length)}`);
+    else if (!line.startsWith(LOOK_LINE)) print(...args);
+  };
+  try {
+    runBuild(flags, gate);
+  } finally {
+    console.log = print;
+  }
+}
+
+/** The pages and the atlas against the input's: a line saying which are byte-identical. */
+function pagesLine(inputAtlas: string, inputPages: readonly InputPage[], outAtlas: string, buildDir: string, outPages: readonly string[]): string {
+  const inputBytes = new Map(inputPages.map((p) => [p.page.name, p.path]));
+  const same = outPages.filter((name) => {
+    const from = inputBytes.get(name);
+    return from !== undefined && readFileSync(from).equals(readFileSync(join(buildDir, name)));
+  });
+  if (inputAtlas === outAtlas && same.length === outPages.length && outPages.length === inputPages.length) {
+    return `  ..    pages  skeleton.atlas and all ${outPages.length} page(s) byte-identical to the input's — these settings pack these regions as the input was packed`;
+  }
+  return (
+    `  ..    pages  skeleton.atlas ${inputAtlas === outAtlas ? 'byte-identical to' : 'differs from'} the input's; ${same.length} of ${outPages.length} page(s) byte-identical to the input's page of the same name ` +
+    `(the input had ${inputPages.length}) — pages move under other pack settings; what (a) holds is every region`
+  );
+}
+
+/**
+ * repack — the command body both entries register, with the entry's own gate
+ * (`build`'s). `plant` is the selftest's (`RepackPlant`).
+ */
+export function cmdRepack({ flags, positional }: CommandArgs, gate: BuildGate, plant?: RepackPlant): void {
+  refuseForeignFlags(flags);
+  if (positional.length !== 1) throw new UsageError(`repack takes one path — the build directory, or its skeleton.json — and was given ${positional.length}`);
+  // Every flag read before anything is: a typo is a usage error, never a default.
+  const packing: Record<string, string> = {
+    'page-size': String(readIntFlag(flags, 'page-size', DEFAULT_PAGE_SIZE)),
+    padding: String(readIntFlag(flags, 'padding', DEFAULT_PADDING)),
+    'page-edges': readPageEdges(flags),
+    'pack-shape': readPackShape(flags),
+    profile: readProfile(flags),
+  };
+  const stage = readStageFlag(flags.stage);
+  const out = readOut(flags);
+  const input = resolveBuild(positional[0], flags.atlas);
+  if (input.atlas !== 'there') throw new UsageError(input.atlasRefusal);
+  const skeletonText = readSkeletonText(input.skeletonPath);
+  const atlasText = readFileSync(input.atlasPath, 'utf8');
+  const parsed = parseAtlasText(atlasText);
+
+  console.log(`rigc repack ${input.skeletonPath}`);
+  console.log(`  ..    atlas  ${input.atlasPath}`);
+  console.log(`  ..    out    ${out}`);
+  console.log(`  ..    pack   page-size ${packing['page-size']}, padding ${packing.padding}, page-edges ${packing['page-edges']}, pack-shape ${packing['pack-shape']}, profile ${packing.profile}`);
+
+  // What the atlas cannot carry through a repack, all of it, before anything is made.
+  const { refusals, pages } = atlasRefusals(parsed, dirname(input.atlasPath));
+  const modelText = modelTextBeside(input.skeletonPath, skeletonText);
+  const disagreement = modelText === undefined ? null : documentDisagreements((parseJsonNamed(modelText, join(dirname(input.skeletonPath), MODEL_DOCUMENT_FILE)) as { pages?: unknown }).pages, parsed);
+  if (disagreement !== null) {
+    refusals.push(
+      ...disagreement.lines.map(
+        (line) => `the atlas and ${MODEL_DOCUMENT_FILE} beside it disagree — ${line}; the document is the record of where the build placed each region, so one of the two was edited after it was written`,
+      ),
+    );
+  }
+  if (refusals.length > 0) {
+    throw new RepackError(
+      `${input.atlasPath} cannot be lifted exactly — ${refusals.length} reason(s), and nothing was written:\n${refusals.map((r) => `  ${r}`).join('\n')}`,
+    );
+  }
+  console.log(
+    `  ..    model  ${
+      disagreement === null
+        ? `no ${MODEL_DOCUMENT_FILE} of this skeleton beside it (or one stating no pages); the atlas is read as it stands`
+        : `the atlas held to ${MODEL_DOCUMENT_FILE}'s pages beside it: ${disagreement.regions} region(s), every placement field equal`
+    }`,
+  );
+
+  const documentStage = documentStageBeside(input.skeletonPath, skeletonText);
+  const work = mkdtempSync(join(tmpdir(), REPACK_WORK_PREFIX));
+  console.error(`rigc repack: work directory ${work}`);
+  const removeWork = (): void => rmSync(work, { recursive: true, force: true });
+  // The `process.exit` inside `runBuild` (a red gate) and the refusal chain's are seen by no `finally`.
+  const onExit = (code: number): void => {
+    removeWork();
+    if (code !== 0) console.error(`rigc repack: nothing was written to ${out}; the work directory ${work} was removed`);
+  };
+  process.on('exit', onExit);
+  try {
+    const liftDir = join(work, 'lift');
+    const specsDir = join(work, 'specs');
+    const buildDir = join(work, 'build');
+    const lifted = liftAtlas(pages, liftDir);
+    console.log(
+      `  ..    lift   ${lifted.parts.size} region(s) off ${pages.length} page(s), each named once: ${lifted.turned} turned on its page, ${lifted.trimmed} trimmed of whitespace — ` +
+        'each lifted as the drawing it is (extractRegion)',
+    );
+    if (plant !== undefined) plant(liftDir);
+
+    let result: { rig: unknown; motion: unknown; findings: IngestFinding[] };
+    try {
+      result = ingest(parseJsonNamed(skeletonText, input.skeletonPath), ingestOptionsFor(input.skeletonPath, specsDir, liftDir, stage, flags['stage-box'], documentStage));
+    } catch (err) {
+      if (err instanceof IngestError) throw new RepackError(`ingest refused the skeleton: ${err.message} — nothing was written`, 2);
+      if (!(err instanceof IngestSpecRefused)) throw err;
+      result = { rig: err.rig, motion: err.motion, findings: err.findings };
+    }
+    console.log(stageLine(result.rig as Parameters<typeof stageLine>[0], stage !== undefined, flags['stage-box'], documentStage));
+    const blockers = result.findings.filter((f) => f.kind === 'blocker');
+    console.log(`  ..    ingest ${result.findings.length} finding(s), ${blockers.length} blocker(s)`);
+    for (const line of findingLines(result.findings)) console.log(line);
+    if (blockers.length > 0) {
+      throw new RepackError(
+        `ingest found ${blockers.length} blocker(s) (${[...new Set(blockers.map((f) => f.code))].join(', ')}), so a rebuild would not be the skeleton that was read — nothing was written`,
+      );
+    }
+    mkdirSync(specsDir, { recursive: true });
+    const rigPath = join(specsDir, 'rig.json');
+    const motionPath = join(specsDir, 'motion.json');
+    writeFileSync(rigPath, `${JSON.stringify(result.rig, null, 2)}\n`);
+    writeFileSync(motionPath, `${JSON.stringify(result.motion, null, 2)}\n`);
+
+    // (c) `build --pack` through the entry's own gate. It returns only green; a red gate exits from inside it.
+    stagedBuild({ rig: rigPath, motion: motionPath, out: buildDir, pack: 'true', ...packing }, gate);
+
+    // (a) and (b), both before the first write.
+    const outAtlas = readFileSync(join(buildDir, 'skeleton.atlas'), 'utf8');
+    const repacked = atlasRefusals(parseAtlasText(outAtlas), buildDir);
+    if (repacked.refusals.length > 0) {
+      throw new Error(`internal: the repacked atlas is one this command would refuse to lift:\n${repacked.refusals.join('\n')}`);
+    }
+    const outSkeleton = readFileSync(join(buildDir, 'skeleton.json'), 'utf8');
+    const owned = packing['pack-shape'] === 'polygon' ? polygonOwnedTexels(outSkeleton, lifted.parts, Number(packing.padding)) : undefined;
+    const regions = regionDifferences(lifted.parts, liftAtlas(repacked.pages).parts, owned);
+    const lost: string[] = [];
+    if (regions.differences.length > 0) lost.push(`(a) ${regions.differences.length} region(s) are not pixel-identical to the input's:`, ...regions.differences.map((d) => `  ${d}`));
+    else {
+      console.log(
+        `  ..    check  (a) regions: ${regions.identical} of ${lifted.parts.size} pixel-identical, by name, to the same region lifted off the input's pages — ` +
+          (regions.byFootprint === 0
+            ? 'each over its whole rectangle'
+            : `${regions.identical - regions.byFootprint} over the whole rectangle, ${regions.byFootprint} that only meshes draw over the footprint a polygon page keeps as its own (the rest of its rectangle may hold a neighbour, by design)`),
+      );
+    }
+    const accepting = flags[ACCEPT_FLAG] !== undefined;
+    if (outSkeleton === skeletonText) {
+      console.log(
+        "  ..    check  (b) skeleton.json: byte-identical to the input's — the pack owns none of it" +
+          (accepting ? `; --${ACCEPT_FLAG} accepted nothing, because there was nothing to accept` : ''),
+      );
+    } else {
+      // Accepted, every path is printed: an accepted difference nobody is shown is the silence the check exists to remove.
+      const diff = skeletonDifferences(parseJsonNamed(skeletonText, input.skeletonPath), parseJsonNamed(outSkeleton, join(buildDir, 'skeleton.json')), accepting ? Infinity : SKELETON_DIFFERENCES_SHOWN);
+      const head =
+        diff.total === 0
+          ? `skeleton.json: the rebuild states the same values in other bytes — ${firstLineApart(skeletonText, outSkeleton)}`
+          : `skeleton.json: ${diff.total} place(s) differ from the input`;
+      if (accepting) {
+        console.log(`  ..    check  (b) ${head}, accepted by --${ACCEPT_FLAG} — the output's skeleton is this rigc's rebuild, not the input's bytes:`);
+        for (const line of diff.lines) console.log(`  ..             ${line}`);
+      } else {
+        lost.push(
+          `(b) ${head}, which the pack does not own${diff.total > diff.lines.length ? ` (the first ${diff.lines.length})` : ''}:`,
+          ...diff.lines.map((d) => `  ${d}`),
+          '  a repack changes where regions sit and nothing in the skeleton; this skeleton is not what this rigc writes from what it states. ' +
+            `--${ACCEPT_FLAG} writes the rebuild anyway — the skeleton this rigc writes from what the input states, every difference listed — ` +
+            'with check (a) and the gate exactly as they are; a build written before 2.2.0, whose header was the stage, differs here in its header box and nowhere else',
+        );
+      }
+    }
+    if (lost.length > 0) throw new RepackError(`the repack lost something, so nothing was written to ${out}:\n${lost.map((l) => `  ${l}`).join('\n')}`);
+    console.log('  ..    check  (c) gate: green — the report above, on the compile and on the packed pair');
+
+    const outParsed = parseAtlasText(outAtlas);
+    const outPages = outParsed.pages.map((p) => p.name);
+    const staged = readdirSync(buildDir).sort();
+    const expected = [...BUILD_TEXTS, ...outPages].sort();
+    if (staged.join('\n') !== expected.join('\n')) throw new Error(`internal: the staged build holds [${staged.join(', ')}], not [${expected.join(', ')}]`);
+    console.log(pagesLine(atlasText, pages, outAtlas, buildDir, outPages));
+
+    mkdirSync(out, { recursive: true });
+    for (const name of [...outPages, ...BUILD_TEXTS]) {
+      copyFileSync(join(buildDir, name), join(out, name));
+      console.log(`rigc: wrote ${join(out, name)}`);
+    }
+    console.log(gate.look(out));
+  } finally {
+    removeWork();
+    process.off('exit', onExit);
+  }
+}

package/src/cli/shared.ts

@@ -45,6 +45,7 @@ import { CheckError } from '../check.ts';
 import { IngestError, type IngestStage } from '../ingest.ts';
 import { NotAPngError } from '../png.ts';
 import { PoseError } from '../pose.ts';
+import { RepackError } from '../repack.ts';
 import { SpineRuntimeError, SPINE_SIDE_ABSENT } from '../spine_side.ts';
 import type { CompileResult, DroppedState } from '../types.ts';
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
@@ -139,7 +140,7 @@ export function readVersion(): string {
  * needs a value` (issue #328). `CLI10`/`CLI11` in `selftest.ts` now hold the two
  * halves together by reading `--help` rather than by naming a flag.
  */
-const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry']);
+const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'accept-skeleton-differences']);
 
 /**
  * The flags a command is allowed to spell more than once.
@@ -1101,6 +1102,17 @@ const FLAG_MEANINGS: Record<string, string> = {
     'so the flag is for a file that really has none rather than for editor exports as a class. ⛔ Beside a ' +
     'skeleton that already declares a box it is REFUSED rather than ignored: two sources for one value, and the ' +
     'file is the record of what was measured',
+  'accept-skeleton-differences':
+    'write the repack even where the rebuilt skeleton.json differs from the input\'s, and print every differing path ' +
+    'with both values (default: refused naming them). It says only where the two differ, never why — a build written ' +
+    'before 2.2.0, whose header box was the stage, differs in those four fields and nowhere else. Region identity and ' +
+    'the gate hold exactly as without it; beside an input that needs none, the check line says it accepted nothing',
+  'stage-box':
+    'the slot whose bounding box carries the stage — what `build` writes for a rig that asks for one ' +
+    '(`skeleton.stageBox`). Its four corners are read as the rebuild\'s stage in place of the header\'s box, which ' +
+    'is the setup-pose bounding box, and the rebuilt spec asks for the same box rather than transcribing it. Only a ' +
+    'box `build` could write back is read: anything else in that slot is refused by name, and without the flag no ' +
+    'slot is read as the stage because of its name',
   help: "show this command's flags and exit",
 };
 
@@ -1154,6 +1166,7 @@ const FLAG_VALUES: Record<string, string> = {
   name: '<n>',
   art: 'loose|none',
   stage: '<x,y,w,h>',
+  'stage-box': '<slot>',
   dir: '<path>',
 };
 
@@ -1295,6 +1308,67 @@ export const COMMANDS: CommandDoc[] = [
       'profile',
     ],
   },
+  {
+    name: 'repack',
+    runtime: {
+      for: 'the rebuild it writes is gated by build\'s gate, which round-trips it through spine-core',
+      core: {
+        usage: [
+          `rigc repack <dir | skeleton.json> --out <dir> [--atlas <path>] [--page-size ${DEFAULT_PAGE_SIZE}] [--padding ${DEFAULT_PADDING}] [--page-edges pot|free] [--pack-shape rect|polygon] [--profile spine|spine-html] [--stage x,y,w,h] [--stage-box <slot>] [--accept-skeleton-differences]   (gated without spine-core — see repack --help)`,
+        ],
+        notes: [
+          'a packed build repacked from its own output — skeleton.json, skeleton.atlas and the',
+          'pages: every region lifted off its page, the skeleton read back (ingest --art loose),',
+          'and build --pack over the lifted parts, in a work directory under the system temp',
+          'directory that is removed when the command ends. Nothing reaches --out until three',
+          'things are shown, each on its own line: (a) every region lifted off the new pages is',
+          'pixel-identical, by name, to the same region off the input\'s (under --pack-shape',
+          'polygon, a region only meshes draw over the footprint the page keeps as its own); (b) the rebuilt',
+          'skeleton.json is byte-identical to the input\'s — the pack owns the atlas and the pages',
+          'and none of the skeleton; (c) the gate is green. On this entry that gate is build\'s',
+          'here: the model side over the document and the round trip\'s own rules restated over',
+          'the emitted text, A00_ROUNDTRIP_PARSE a SKIP naming spine-core. An atlas the lift',
+          'cannot read exactly is refused by name before anything is made: docs/AUTHORING.md',
+          '§0.4 lists what is accepted and what is refused, and why.',
+        ],
+      },
+    },
+    spineFormat: true,
+    usage: [
+      `rigc repack <dir | skeleton.json> --out <dir> [--atlas <path>] [--page-size ${DEFAULT_PAGE_SIZE}] [--padding ${DEFAULT_PADDING}] [--page-edges pot|free] [--pack-shape rect|polygon] [--profile spine|spine-html] [--stage x,y,w,h] [--stage-box <slot>] [--accept-skeleton-differences]`,
+    ],
+    flags: ['out', 'atlas', 'page-size', 'padding', 'page-edges', 'pack-shape', 'profile', 'stage', 'stage-box', 'accept-skeleton-differences'],
+    overrides: {
+      out: {
+        value: '<dir>',
+        meaning:
+          'the directory the repacked build is written into — skeleton.json, skeleton.atlas, skeleton.model.json and the ' +
+          'pages, exactly what build --pack writes — absent or empty, and refused otherwise: a page an earlier pack wrote ' +
+          'and this one does not would stay beside the new atlas with nothing naming it. Written only after the three checks',
+      },
+      atlas: { meaning: "the build's atlas, when it is not skeleton.atlas beside the skeleton (a skeleton.json path with several .atlas files beside it needs it)" },
+    },
+    notes: [
+      'a packed build repacked from its own output — skeleton.json, skeleton.atlas and the',
+      'pages: every region lifted off its page, the skeleton read back (ingest --art loose),',
+      'and build --pack over the lifted parts with the packing flags above, which mean what',
+      'they mean to build --pack (repack always packs). The work runs in a directory under the',
+      'system temp directory that is removed when the command ends. Nothing reaches --out until',
+      'three things are shown, each on its own line: (a) every region lifted off the new pages',
+      'is pixel-identical, by name, to the same region off the input\'s (under --pack-shape',
+      'polygon, a region only meshes draw over the footprint the page keeps as its own); (b) the rebuilt',
+      'skeleton.json is byte-identical to the input\'s — the pack owns the atlas and the pages',
+      'and none of the skeleton (--accept-skeleton-differences writes a rebuild that differs,',
+      'every differing path printed); (c) build\'s gate is green. Under the settings the input was',
+      'packed with, a line says the atlas and pages came back byte-identical; under others the',
+      'pages differ by design and (a) is the guarantee. An atlas the lift cannot read exactly',
+      '— a page scale, premultiplied alpha, a region named twice, a region off its page, a page',
+      'that is missing — is refused by name before anything is made: docs/AUTHORING.md §0.4',
+      'lists what is accepted and what is refused, and why. The stage line says which stage the',
+      'rebuild declared and where it was read (--stage, the skeleton.model.json beside the',
+      'pair, or the header\'s box).',
+    ],
+  },
   {
     name: 'explain',
     runtime: false,
@@ -1328,8 +1402,8 @@ export const COMMANDS: CommandDoc[] = [
     name: 'ingest',
     runtime: false,
     spineFormat: true,
-    usage: ['rigc ingest <skeleton.json> --out <dir> [--name <n>] [--art loose|none] [--images <dir>] [--stage x,y,w,h]'],
-    flags: ['out', 'name', 'art', 'images', 'stage'],
+    usage: ['rigc ingest <skeleton.json> --out <dir> [--name <n>] [--art loose|none] [--images <dir>] [--stage x,y,w,h] [--stage-box <slot>]'],
+    flags: ['out', 'name', 'art', 'images', 'stage', 'stage-box'],
     overrides: {
       out: {
         value: '<dir>',
@@ -1633,6 +1707,18 @@ const USAGE_PARAGRAPHS: ReadonlyArray<{ about: readonly string[] | { flag: strin
       'rules that profile left out.',
     ],
   },
+  {
+    about: ['repack'],
+    lines: () => [
+      'repack takes a packed build whose parts were not kept — skeleton.json, skeleton.atlas and',
+      'the pages — and packs it again under build --pack\'s packing flags, so a packer',
+      'improvement reaches a build without its parts:',
+      '  rigc repack build/ --out build.free/ --page-edges free --pack-shape polygon',
+      'It writes only after every region is shown pixel-identical, the skeleton byte-identical',
+      'and the gate green, and refuses by name an atlas it cannot lift exactly. See',
+      '`rigc repack --help`.',
+    ],
+  },
   {
     about: ['check'],
     lines: () => [
@@ -2530,6 +2616,13 @@ function refuse(err: unknown, command: string | undefined, USAGE: string, entry:
     console.error(`rigc ingest: ${err.message}`);
     process.exit(2);
   }
+  // A repack refused (issue #1169): an atlas it cannot lift exactly, a repack that lost something, or an `--out`
+  // it will not write into. The message names every reason and says that nothing was written; `status` is 1 for a
+  // file that is not what a repack needs and 2 for an invocation that has to change.
+  if (err instanceof RepackError) {
+    console.error(`rigc repack: ${err.message}`);
+    process.exit(err.status);
+  }
   // A page or frame that is not a PNG rigc can read, from any command that
   // opens one (`render`, `check`, `preview`, …) — issue #732. The sentence is
   // the one reader's and already names the file, what it is and what rigc

package/src/cli/spine_commands.ts

@@ -20,6 +20,7 @@ import { atlasPageNames } from '../render.ts';
 import { BoneDistError } from '../bonedist.ts';
 import { assertionCountForProfile, CLI_DEFAULT_PROFILE, reportLines, validate, type ValidateProfile } from '../validate.ts';
 import { type CliRefusal, type CommandRun, DEFAULT_BALLOT, PACKAGE_ROOT, DEFAULT_LEDGER, parseJsonNamed, readAnimationFlag, readJsonFile, readPackageMeta, readSkeletonText, readVersion, resolveBuild, resolveCut, resolveViewable, runCheck, spinePairOf, type BuildGate, runBuild, readProfile, STAGELESS_FRAMING, UsageError, writeJson, modelTextBeside } from './shared.ts';
+import { cmdRepack } from './repack.ts';
 import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 
@@ -801,6 +802,7 @@ export function cmdBoneDist(flags: Record<string, string>): void {
  */
 export const SPINE_COMMAND_RUNS: Readonly<Record<string, CommandRun>> = {
   build: ({ flags }) => cmdBuild(flags),
+  repack: (args) => cmdRepack(args, ROUND_TRIP_GATE),
   validate: ({ flags, positional }) => cmdValidate(flags, positional),
   bench: ({ flags, positional }) => cmdBench(flags, positional),
   bonedist: ({ flags }) => cmdBoneDist(flags),