@rig-c/parts 1.14.0 → 1.16.0

package/README.md

@@ -291,9 +291,13 @@ agent skill.
 | `loop --frames <dir> --out <file.gif \| file.png> [--palette]` | encode a rendered idle as a looping GIF, lossless APNG, or indexed APNG (`--palette`) |
 | `build --config --source --full --head --out [--seam] [--project] [--loop] [--lead-in <periods>] [--requirements] [--seam-pairs] [--keep-stills] [--idle-keys ctl\|direct]` | assemble, rig and check in one process, stopping at the first refusal; `--requirements`, `--seam-pairs` and `--keep-stills` are forwarded to check, `--idle-keys` to rig; `--lead-in` (with `--loop`) encodes the loop from the last of n + 1 idle periods played back to back, for a rig whose physics does not end where the render starts it |
 | `compose --scene <scene.json> --out [--requirements] [--accept]` | bind several characters' green builds into one rig (or, under `--accept`, builds failing only the bars named — for looking, not shipping): every name prefixed `<id>:` under one shared root, each character's offset added at its first-level bones, an optional background plate (its provenance recorded, judged by nothing) drawn first, and the draw order between the characters' slots as the scene file declares it — nothing inferred, nothing scaled; gated through rig-c as `rig` is, then checked ([AUTHORING §7](docs/AUTHORING.md), *Composing several characters*) |
+| `guide <RULE \| §<n> \| §<n>.<m> \| §<n>.<m>.<k>>` | print the one row of [docs/AUTHORING.md](docs/AUTHORING.md) that names a rule (a refusal and the bar it enforces, `CHECK_<LINE>` and `<LINE>`, print together), or one section, `###` subsection or `####` under it, read from the installed file when it runs |
 
 `rig-parts --help` has every flag. Exit codes: 0 done, 1 input refused (every
 reason is a FAIL line), 2 a usage error or a command this version does not implement.
+Every FAIL line ends with `(see rig-parts guide <RULE>)`, the command that prints the
+guide's row for that rule, and each row is anchored on the web as
+`docs/AUTHORING.md#<RULE>`.
 
 What 1.0.0 holds stable — these commands and their flags, the config
 fields, the files a build writes and their spec ids, the environment, and what this

package/cli.ts

@@ -17,10 +17,11 @@ import { tmpdir } from 'node:os';
 import { basename, dirname, extname, join } from 'node:path';
 import { DEFAULT_PROJECT_RULE, DEFAULT_SEAM_RULE, HOLES_LISTED, PROJECT_RULES, type ProjectRule, proposeFields, proposePlan, SEAM_RULES, type SeamRule } from './src/assemble.ts';
 import { assembleStage, build, checkStage, ERROR_MAP_FILE, loopStage, readRuns, readSource, rigStage, suppliedCheckFlag } from './src/build.ts';
-import { ACCEPTABLE_BARS, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, findRigc, PACK_SHAPES, type PackShape, PAGE_EDGES, type PageEdges, PARTS_HOME_SENTENCE, RIGC_GEOMETRY_VERSION, type RigcRunner, NO_PARTS_SENTENCE, SEAM_MEAN_BAR, SOURCE_SENTENCE, SEAM_PX_BAR, SEAM_PX_LEVEL, SPINEBOY_YARDSTICK, TEXTURE_STRETCH_CEILING } from './src/check.ts';
+import { ACCEPTABLE_BARS, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, findRigc, PACK_SHAPES, rigcRunnerAt, type PackShape, PAGE_EDGES, type PageEdges, PARTS_HOME_SENTENCE, RIGC_GEOMETRY_VERSION, type RigcRunner, NO_PARTS_SENTENCE, SEAM_MEAN_BAR, SOURCE_SENTENCE, SEAM_PX_BAR, SEAM_PX_LEVEL, SPINEBOY_YARDSTICK, TEXTURE_STRETCH_CEILING } from './src/check.ts';
 import { ComfyClient, resolveHost, runPainting, runSeeThrough } from './src/comfy/index.ts';
 import { type CharacterConfig, loadConfig, loadEarlyConfig, loadPaintConfig } from './src/config.ts';
-import { PartsError, problemLine } from './src/errors.ts';
+import { failLine, guidePointer, PartsError } from './src/errors.ts';
+import { GUIDE_DOC, type GuideAnswer, guideRule, guideSection } from './src/guide.ts';
 import { proposeHeadBox } from './src/headbox.ts';
 import { makeInputs } from './src/inputs.ts';
 import { idleKeysOf, isIdleKeys } from './src/rig.ts';
@@ -347,8 +348,8 @@ usage:
       BREATH_VISIBLE, BLINK_NO_HOLE, TIP_OVER_ROOT, STILL_REGIONS_DARK and
       RECOMPOSITE_HOLES; without an idle the loop and every line that reads idle
       frames, and no idle is rendered. The gate always runs. When motion.json
-      holds an animation beside the idle, ANIMATIONS_DO_NOT_FOLD reads each with
-      rigc render --folds, physics constraints left out: a mesh triangle turned
+      holds an animation, ANIMATIONS_DO_NOT_FOLD reads each, the idle included,
+      with rigc render --folds, physics constraints left out: a mesh triangle turned
       over against the setup pose fails, unless the --requirements file's
       may_fold declares that slot and animation with a why. The last line says
       how many of the bars measured — nine, ten with the fold bar — and names
@@ -590,6 +591,23 @@ usage:
       line and ${SCENE_REPORT_FILE} name what was accepted, and the run exits 1.
       Exit 0 when the check is PASS and nothing was accepted, 1 otherwise.
 
+  rig-parts guide <RULE | §<n> | §<n>.<m> | §<n>.<m>.<k>>
+      Print a slice of ${GUIDE_DOC}, the guide this package ships, read
+      from the installed file at the moment of the call; nothing is kept
+      apart from it. Every FAIL line ends with the command that prints its
+      rule's row: "(see rig-parts guide <RULE>)". guide <RULE> prints
+      "docs/AUTHORING.md §<addr>, line <N> — under "<heading>"" and the one
+      row naming the rule; a refusal and the bar it enforces (CHECK_<LINE>
+      and <LINE>) print one after the other, joined by "paired with
+      <OTHER>:". A name no row holds is refused on stderr
+      (GUIDE_RULE_KNOWN), with the three nearest names the guide holds,
+      and nothing printed in their place. guide §<n> prints section n,
+      after its subsections' numbers and sizes in KB; §<n>.<m>
+      is the m-th ### heading under it and §<n>.<m>.<k> the k-th #### under
+      that, counted as the file stands (the headings carry no number), and
+      §<n>.<m> lists its ####s as §<n> lists its ###s. Exit 0 printed, 1
+      refused, 2 usage.
+
   rig-parts --version
   rig-parts --help
 
@@ -598,7 +616,7 @@ ${LATER.length === 0 ? '' : `not implemented in this version (each exits 2):\n${
 
 function printRefusal(err: unknown): number {
   if (err instanceof PartsError) {
-    for (const p of err.problems) console.log(`  FAIL  ${problemLine(p)}`);
+    for (const p of err.problems) console.log(failLine(p));
     console.log(`refused: ${err.problems.length} problem(s)`);
     return EXIT_REFUSED;
   }
@@ -606,11 +624,28 @@ function printRefusal(err: unknown): number {
 }
 
 function usage(message: string): number {
-  console.log(`  FAIL  USAGE: ${message}`);
+  console.log(`  FAIL  USAGE: ${message}${guidePointer('USAGE')}`);
   console.log('rig-parts --help lists the commands');
   return EXIT_USAGE;
 }
 
+/** `guide`: one argument, a rule name or a section; the slice printed, or the refusal. */
+function cmdGuide(args: string[]): number {
+  if (args.length !== 1) return usage(`guide takes one rule name or one §<n> / §<n>.<m> / §<n>.<m>.<k>; got ${args.length} argument(s)`);
+  if (args[0].startsWith('-')) return usage(`guide takes no flag; "${args[0]}" is neither a rule name nor §<n> / §<n>.<m>`);
+  const path = join(import.meta.dir, GUIDE_DOC);
+  if (!existsSync(path)) return printRefusal(new PartsError([{ code: 'GUIDE_FILE_PRESENT', object: path, detail: 'no such file; the guide ships in the package beside cli.ts' }]));
+  const text = readFileSync(path, 'utf8');
+  const answer: GuideAnswer = args[0].startsWith('§') ? guideSection(text, args[0]) : guideRule(text, args[0]);
+  // The shared form: an unknown name or section is one coded FAIL line on stderr, exit 1.
+  if ('problem' in answer) {
+    console.error(failLine(answer.problem));
+    return EXIT_REFUSED;
+  }
+  for (const l of answer.lines) console.log(l);
+  return EXIT_OK;
+}
+
 function fixed(v: number | null): string {
   return v === null ? '-' : v.toFixed(4);
 }
@@ -655,7 +690,8 @@ function printLayerTable(set: LayerSet): void {
 /**
  * Every flag each command takes: `valued` flags carry a value, `switches` are bare. Each parser reads its row to
  * decide what it accepts, and {@link notTaken} prints the same row in the unknown-flag refusal, so the refusal
- * lists exactly the flags the parser accepts (CL26). `layers` takes one positional path and no flag, so it has no row.
+ * lists exactly the flags the parser accepts (CL26). `layers` takes one positional path and `guide` one positional
+ * argument, and neither takes a flag, so neither has a row.
  */
 const TAKES = {
   sheet: { valued: ['--source', '--layers', '--out', '--cell', '--cols'], switches: [] },
@@ -825,14 +861,15 @@ function cmdRig(args: string[]): number {
  * `cli_core.ts` and rigc's own validator where it does not. No stage runs a
  * rigc source file by path: under rig-c 2.0, `cli.ts` by path is the
  * spine-core entry whether or not spine-core is there. `src/` is pure and takes
- * the spawn from here.
+ * the spawn from here. A call that fails carries which rigc ran it, path and
+ * version ({@link rigcRunnerAt}, issue #337), and every refusal quoting it says so.
  */
 function rigcRunner(bin: string): RigcRunner {
-  return (args) => {
-    const r = spawnSync(bin, [...args], { encoding: 'utf8', maxBuffer: 1 << 28 });
-    if (r.error !== undefined) return { status: 127, out: `could not start ${bin}: ${r.error.message}` };
+  return rigcRunnerAt(bin, (b, args) => {
+    const r = spawnSync(b, [...args], { encoding: 'utf8', maxBuffer: 1 << 28 });
+    if (r.error !== undefined) return { status: 127, out: `could not start ${b}: ${r.error.message}` };
     return { status: r.status ?? 1, out: `${r.stdout ?? ''}${r.stderr ?? ''}` };
-  };
+  });
 }
 
 /** The command's valued flags as `--flag value` pairs, each one its {@link TAKES} row holds; `required` must all be given. Its bare switches are taken out by the caller before this reads the rest. A string is a usage error. */
@@ -1046,7 +1083,7 @@ function cmdCompare(args: string[]): number {
     console.log(`rig-parts compare: left ${left}, right ${right}${map === null ? ', no map' : `, map ${map}`}`);
     for (const l of structureLines(c)) console.log(l);
     const missing = requiredProblems(c, map ?? 'the map');
-    for (const p of missing) console.log(`  FAIL  ${problemLine(p)}`);
+    for (const p of missing) console.log(failLine(p));
     return missing.length > 0 ? EXIT_REFUSED : EXIT_OK;
   } catch (err) {
     return printRefusal(err);
@@ -1397,9 +1434,10 @@ function main(argv: string[]): number | Promise<number> {
   if (command === 'build') return cmdBuild(rest);
   if (command === 'compose') return cmdCompose(rest);
   if (command === 'mesh-draft') return cmdMeshDraft(rest);
+  if (command === 'guide') return cmdGuide(rest);
   const later = LATER.find(([name]) => name === command);
   if (later !== undefined) {
-    console.log(`  FAIL  NOT_IMPLEMENTED: \`rig-parts ${command}\` (${later[1]}) is not implemented in this version, ${version()}`);
+    console.log(`  FAIL  NOT_IMPLEMENTED: \`rig-parts ${command}\` (${later[1]}) is not implemented in this version, ${version()}${guidePointer('NOT_IMPLEMENTED')}`);
     return EXIT_USAGE;
   }
   return usage(`unknown command "${command}"`);