@roster-lock/config-editor-cli 0.0.1

package/tests/commands/from-lock.spec.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join as pathJoin } from "node:path";
+import { EMPTY_ROSTER_LOCK } from "@roster-lock/shared";
+import { cloneJSON } from "@roster-lock/utils";
+import { RosterLockV1Config, RosterLockV1Draft } from "@roster-lock/types";
+import { fromLockCommand } from "../../src/commands/draft/from-lock";
+
+async function runFromLock(args: Array<string>){
+  const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+  process.exitCode = undefined;
+
+  await fromLockCommand.parseAsync(["node", "from-lock", ...args]);
+
+  const logs = logSpy.mock.calls.map((call) => call.join(" "));
+  logSpy.mockRestore();
+  return logs;
+}
+
+function buildLockWithRoster(): RosterLockV1Config {
+  const lock = cloneJSON(EMPTY_ROSTER_LOCK);
+  lock.title = "My Game";
+  lock.engine.pieceDefinitions["character"] = {
+    selectionStrategy: "mandatory",
+    requires: [],
+    pathVariables: [],
+    assets: [{ name: "sprite", classification: "media", count: 1, glob: ["*.png"] }],
+  };
+  lock.rosters["character"] = [{
+    id: "@author/blue",
+    version: { logic: "a".repeat(64), media: "b".repeat(64), docs: "c".repeat(64) },
+    humanInfo: { name: "Blue", author: "author", url: "https://example.com/blue" },
+    downloadSources: ["https://example.com/blue.tar"],
+    pathVariables: {},
+    requiredPieces: {},
+  }];
+  lock.selection.piece["character"] = {
+    type: "unselectable",
+  };
+  return lock;
+}
+
+describe("draft from-lock", () => {
+  let tempDir: string;
+  let lockPath: string;
+  let draftPath: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(pathJoin(tmpdir(), "rosterlock-from-lock-"));
+    lockPath = pathJoin(tempDir, "my-game-1.0.0.rosterlock.json");
+    draftPath = pathJoin(tempDir, "out.rosterlock.draft.json");
+    writeFileSync(lockPath, JSON.stringify(buildLockWithRoster()));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("copies the lock's rosters and selection into the draft by default", async () => {
+    await runFromLock([lockPath, draftPath]);
+
+    const draft: RosterLockV1Draft = JSON.parse(readFileSync(draftPath, "utf-8"));
+    expect(draft.stagedLock.rosters["character"]).toHaveLength(1);
+    expect(draft.stagedLock.selection.piece["character"]).toBeDefined();
+    expect(draft.previousLock.rosters["character"]).toHaveLength(1);
+  });
+
+  it("--clear-rosters keeps the engine but empties rosters and per-type selection", async () => {
+    const logs = await runFromLock([lockPath, draftPath, "--clear-rosters"]);
+
+    const draft: RosterLockV1Draft = JSON.parse(readFileSync(draftPath, "utf-8"));
+    expect(draft.stagedLock.engine.pieceDefinitions["character"]).toBeDefined();
+    expect(draft.stagedLock.rosters["character"]).toEqual([]);
+    expect(draft.stagedLock.selection.piece).toEqual({});
+    // previousLock is left untouched so future diffs reflect the roster removal
+    expect(draft.previousLock.rosters["character"]).toHaveLength(1);
+    expect(logs.join("\n")).toMatch(/rosters cleared/);
+  });
+});

package/tests/commands/help-arguments.spec.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect } from "vitest";
+import type { Command } from "commander";
+import * as draftCommands from "../../src/commands/draft";
+import * as engineCommands from "../../src/commands/engine";
+import * as rosterCommands from "../../src/commands/roster";
+import * as selectionCommands from "../../src/commands/selection";
+import { validateCommand } from "../../src/commands/validate";
+import { showCommand } from "../../src/commands/show";
+
+// Commander only prints an "Arguments:" section in --help for arguments that have
+// a description, so an argument without one is invisible to a user running --help,
+// even though it's a required positional. This guards against adding a new one
+// without documenting what it expects.
+const allCommands: Array<Command> = [
+  ...Object.values(draftCommands),
+  ...Object.values(engineCommands),
+  ...Object.values(rosterCommands),
+  ...Object.values(selectionCommands),
+  validateCommand,
+  showCommand,
+];
+
+describe("command --help documents every positional argument", () => {
+  for(const command of allCommands){
+    for(const arg of command.registeredArguments){
+      it(`"${command.name()}" argument "${arg.name()}" has a description`, () => {
+        expect(arg.description.length).toBeGreaterThan(0);
+      });
+    }
+  }
+});

package/tests/commands/import-piece.spec.ts

@@ -0,0 +1,228 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join as pathJoin } from "node:path";
+import { EMPTY_ROSTER_DRAFT, EMPTY_ROSTER_LOCK } from "@roster-lock/shared";
+import { cloneJSON } from "@roster-lock/utils";
+import { RosterLockPiece, RosterLockV1Config, RosterLockV1Draft } from "@roster-lock/types";
+
+async function runImportPiece(args: Array<string>){
+  vi.resetModules();
+  const { importPieceCommand } = await import("../../src/commands/roster/import-piece.js");
+
+  process.exitCode = undefined;
+  const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+  await importPieceCommand.parseAsync(["node", "import-piece", ...args]);
+  const logs = logSpy.mock.calls.map((call) => call.join(" "));
+  logSpy.mockRestore();
+  const exitCode = process.exitCode;
+  process.exitCode = undefined;
+  return { logs, exitCode };
+}
+
+const CHARACTER_DEFINITION = {
+  selectionStrategy: "mandatory" as const,
+  requires: [],
+  pathVariables: [],
+  assets: [{ name: "sprite", classification: "media" as const, count: 1, glob: ["*.png"] }],
+};
+
+const CHARACTER_WITH_WEAPON_DEFINITION = {
+  ...CHARACTER_DEFINITION,
+  requires: ["weapon"],
+};
+
+const WEAPON_DEFINITION = {
+  selectionStrategy: "on demand" as const,
+  requires: [],
+  pathVariables: [],
+  assets: [{ name: "sprite", classification: "media" as const, count: 1, glob: ["*.png"] }],
+};
+
+const SOURCE_PIECE: RosterLockPiece = {
+  id: "@author/blue",
+  version: { logic: "a".repeat(64), media: "b".repeat(64), docs: "c".repeat(64) },
+  humanInfo: { name: "Blue", author: "author", url: "https://example.com/blue" },
+  downloadSources: ["https://example.com/blue.tar"],
+  pathVariables: {},
+  requiredPieces: {},
+};
+
+const SOURCE_WEAPON_PIECE: RosterLockPiece = {
+  id: "@author/sword",
+  version: { logic: "d".repeat(64), media: "e".repeat(64), docs: "f".repeat(64) },
+  humanInfo: { name: "Sword", author: "author", url: "https://example.com/sword" },
+  downloadSources: ["https://example.com/sword.tar"],
+  pathVariables: {},
+  requiredPieces: {},
+};
+
+const SOURCE_PIECE_WITH_REQUIRED: RosterLockPiece = {
+  ...cloneJSON(SOURCE_PIECE),
+  requiredPieces: { weapon: { expected: ["@author/sword"], selectable: false } },
+};
+
+describe("roster import-piece", () => {
+  let tempDir: string;
+  let draftPath: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(pathJoin(tmpdir(), "rosterlock-import-piece-"));
+    draftPath = pathJoin(tempDir, "test.rosterlock.draft.json");
+
+    const draft: RosterLockV1Draft = cloneJSON(EMPTY_ROSTER_DRAFT);
+    draft.stagedLock.engine.pieceDefinitions["character"] = cloneJSON(CHARACTER_DEFINITION);
+    draft.stagedLock.rosters["character"] = [];
+    writeFileSync(draftPath, JSON.stringify(draft));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  function readTargetPiece(){
+    const draft: RosterLockV1Draft = JSON.parse(readFileSync(draftPath, "utf-8"));
+    return draft.stagedLock.rosters["character"][0];
+  }
+
+  function writeSourceLock(){
+    const lock: RosterLockV1Config = cloneJSON(EMPTY_ROSTER_LOCK);
+    lock.engine.pieceDefinitions["character"] = cloneJSON(CHARACTER_DEFINITION);
+    lock.rosters["character"] = [cloneJSON(SOURCE_PIECE)];
+    const lockPath = pathJoin(tempDir, "source.rosterlock.json");
+    writeFileSync(lockPath, JSON.stringify(lock));
+    return lockPath;
+  }
+
+  function writeSourceDraft(){
+    const source: RosterLockV1Draft = cloneJSON(EMPTY_ROSTER_DRAFT);
+    source.stagedLock.engine.pieceDefinitions["character"] = cloneJSON(CHARACTER_DEFINITION);
+    source.stagedLock.rosters["character"] = [cloneJSON(SOURCE_PIECE)];
+    const sourcePath = pathJoin(tempDir, "source.rosterlock.draft.json");
+    writeFileSync(sourcePath, JSON.stringify(source));
+    return sourcePath;
+  }
+
+  it("copies a piece from a published lock, trusting its existing hash as-is", async () => {
+    const lockPath = writeSourceLock();
+
+    const { exitCode } = await runImportPiece([lockPath, "character", "@author/blue", "--draft", draftPath]);
+    expect(exitCode).toBeUndefined();
+
+    const piece = readTargetPiece();
+    expect(piece).toEqual(SOURCE_PIECE);
+  });
+
+  it("copies a piece from another draft's staged lock", async () => {
+    const sourcePath = writeSourceDraft();
+
+    const { exitCode } = await runImportPiece([sourcePath, "character", "@author/blue", "--draft", draftPath]);
+    expect(exitCode).toBeUndefined();
+
+    expect(readTargetPiece()).toEqual(SOURCE_PIECE);
+  });
+
+  it("--as imports under a different piece id", async () => {
+    const lockPath = writeSourceLock();
+
+    await runImportPiece([lockPath, "character", "@author/blue", "--as", "@author/blue-renamed", "--draft", draftPath]);
+
+    const piece = readTargetPiece();
+    expect(piece.id).toBe("@author/blue-renamed");
+    expect(piece.version).toEqual(SOURCE_PIECE.version);
+  });
+
+  it("fails for an unknown target piece type", async () => {
+    const lockPath = writeSourceLock();
+
+    const { exitCode } = await runImportPiece([lockPath, "vehicle", "@author/blue", "--draft", draftPath]);
+    expect(exitCode).toBe(1);
+  });
+
+  it("fails for an unknown piece id in the source", async () => {
+    const lockPath = writeSourceLock();
+
+    const { exitCode } = await runImportPiece([lockPath, "character", "@author/missing", "--draft", draftPath]);
+    expect(exitCode).toBe(1);
+  });
+
+  it("fails when a piece with the same id already exists, without --as", async () => {
+    const lockPath = writeSourceLock();
+    await runImportPiece([lockPath, "character", "@author/blue", "--draft", draftPath]);
+
+    const { exitCode } = await runImportPiece([lockPath, "character", "@author/blue", "--draft", draftPath]);
+    expect(exitCode).toBe(1);
+
+    const draft: RosterLockV1Draft = JSON.parse(readFileSync(draftPath, "utf-8"));
+    expect(draft.stagedLock.rosters["character"]).toHaveLength(1);
+  });
+
+  describe("required pieces", () => {
+    function setUpDraftAndSourceWithRequires(){
+      const draft: RosterLockV1Draft = JSON.parse(readFileSync(draftPath, "utf-8"));
+      draft.stagedLock.engine.pieceDefinitions["character"] = cloneJSON(CHARACTER_WITH_WEAPON_DEFINITION);
+      draft.stagedLock.engine.pieceDefinitions["weapon"] = cloneJSON(WEAPON_DEFINITION);
+      draft.stagedLock.rosters["weapon"] = [];
+      writeFileSync(draftPath, JSON.stringify(draft));
+
+      const lock: RosterLockV1Config = cloneJSON(EMPTY_ROSTER_LOCK);
+      lock.engine.pieceDefinitions["character"] = cloneJSON(CHARACTER_WITH_WEAPON_DEFINITION);
+      lock.engine.pieceDefinitions["weapon"] = cloneJSON(WEAPON_DEFINITION);
+      lock.rosters["character"] = [cloneJSON(SOURCE_PIECE_WITH_REQUIRED)];
+      lock.rosters["weapon"] = [cloneJSON(SOURCE_WEAPON_PIECE)];
+      const lockPath = pathJoin(tempDir, "source.rosterlock.json");
+      writeFileSync(lockPath, JSON.stringify(lock));
+      return lockPath;
+    }
+
+    it("also imports a required piece that doesn't yet exist in the target", async () => {
+      const lockPath = setUpDraftAndSourceWithRequires();
+
+      const { exitCode } = await runImportPiece([lockPath, "character", "@author/blue", "--draft", draftPath]);
+      expect(exitCode).toBeUndefined();
+
+      const draft: RosterLockV1Draft = JSON.parse(readFileSync(draftPath, "utf-8"));
+      expect(draft.stagedLock.rosters["weapon"]).toEqual([SOURCE_WEAPON_PIECE]);
+      expect(draft.stagedLock.rosters["character"][0].requiredPieces).toEqual({
+        weapon: { expected: ["@author/sword"], selectable: false },
+      });
+    });
+
+    it("reuses an existing piece of matching version, rewriting the expected id to match it", async () => {
+      const lockPath = setUpDraftAndSourceWithRequires();
+
+      const draft: RosterLockV1Draft = JSON.parse(readFileSync(draftPath, "utf-8"));
+      const existingWeapon: RosterLockPiece = { ...cloneJSON(SOURCE_WEAPON_PIECE), id: "@other/existing-sword" };
+      draft.stagedLock.rosters["weapon"] = [existingWeapon];
+      writeFileSync(draftPath, JSON.stringify(draft));
+
+      const { exitCode } = await runImportPiece([lockPath, "character", "@author/blue", "--draft", draftPath]);
+      expect(exitCode).toBeUndefined();
+
+      const result: RosterLockV1Draft = JSON.parse(readFileSync(draftPath, "utf-8"));
+      expect(result.stagedLock.rosters["weapon"]).toEqual([existingWeapon]);
+      expect(result.stagedLock.rosters["character"][0].requiredPieces).toEqual({
+        weapon: { expected: ["@other/existing-sword"], selectable: false },
+      });
+    });
+
+    it("fails when a required piece id conflicts with a different version already in the target", async () => {
+      const lockPath = setUpDraftAndSourceWithRequires();
+
+      const draft: RosterLockV1Draft = JSON.parse(readFileSync(draftPath, "utf-8"));
+      const conflictingWeapon: RosterLockPiece = {
+        ...cloneJSON(SOURCE_WEAPON_PIECE),
+        version: { logic: "1".repeat(64), media: "2".repeat(64), docs: "3".repeat(64) },
+      };
+      draft.stagedLock.rosters["weapon"] = [conflictingWeapon];
+      writeFileSync(draftPath, JSON.stringify(draft));
+
+      const { exitCode } = await runImportPiece([lockPath, "character", "@author/blue", "--draft", draftPath]);
+      expect(exitCode).toBe(1);
+
+      const result: RosterLockV1Draft = JSON.parse(readFileSync(draftPath, "utf-8"));
+      expect(result.stagedLock.rosters["character"]).toHaveLength(0);
+      expect(result.stagedLock.rosters["weapon"]).toEqual([conflictingWeapon]);
+    });
+  });
+});

package/tests/commands/piece-meta.spec.ts

@@ -0,0 +1,123 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join as pathJoin } from "node:path";
+import { EMPTY_ROSTER_DRAFT } from "@roster-lock/shared";
+import { cloneJSON } from "@roster-lock/utils";
+import { RosterLockV1Draft } from "@roster-lock/types";
+import { pieceMetaSetCommand } from "../../src/commands/piece-meta/set";
+import { pieceMetaShowCommand } from "../../src/commands/piece-meta/show";
+
+async function runPieceMetaSet(args: Array<string>){
+  process.exitCode = undefined;
+  let thrown: unknown;
+  try {
+    await pieceMetaSetCommand.parseAsync(["node", "set", ...args]);
+  } catch(e){
+    thrown = e;
+  }
+  return { thrown };
+}
+
+async function runPieceMetaShow(args: Array<string>){
+  const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+  process.exitCode = undefined;
+  await pieceMetaShowCommand.parseAsync(["node", "show", ...args]);
+  const logs = logSpy.mock.calls.map((call) => call.join(" "));
+  logSpy.mockRestore();
+  return { logs };
+}
+
+describe("piece-meta set/show", () => {
+  let tempDir: string;
+  let draftPath: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(pathJoin(tmpdir(), "rosterlock-piece-meta-"));
+    draftPath = pathJoin(tempDir, "test.rosterlock.draft.json");
+
+    const draft: RosterLockV1Draft = cloneJSON(EMPTY_ROSTER_DRAFT);
+    draft.stagedLock.engine.pieceDefinitions["character"] = {
+      selectionStrategy: "mandatory",
+      requires: [],
+      pathVariables: [],
+      assets: [],
+    };
+    draft.stagedLock.rosters["character"] = [{
+      id: "@author/blue",
+      version: { logic: "a".repeat(64), media: "b".repeat(64), docs: "c".repeat(64) },
+      humanInfo: { name: "Blue", author: "author", url: "https://example.com/blue" },
+      downloadSources: ["https://example.com/blue.tar"],
+      pathVariables: {},
+      requiredPieces: {},
+    }];
+    draft.stagedLock.selection.piece["character"] = { type: "unselectable" };
+    writeFileSync(draftPath, JSON.stringify(draft));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  function readDraftFile(): RosterLockV1Draft {
+    return JSON.parse(readFileSync(draftPath, "utf-8"));
+  }
+
+  it("sets the schema/defaultMeta/values for a piece type, independent of the selection config", async () => {
+    const jsonPath = pathJoin(tempDir, "meta.json");
+    writeFileSync(jsonPath, JSON.stringify({
+      schema: { power: "number" },
+      defaultMeta: { power: 1 },
+      values: { "@author/blue": { power: 5 } },
+    }));
+
+    await runPieceMetaSet(["character", "--draft", draftPath, "--json", jsonPath]);
+
+    const meta = readDraftFile().stagedLock.pieceMeta["character"];
+    expect(meta.schema).toEqual({ power: "number" });
+    expect(meta.defaultMeta).toEqual({ power: 1 });
+    expect(meta.values).toEqual({ "@author/blue": { power: 5 } });
+    // Unrelated to the selection config for that piece type
+    expect(readDraftFile().stagedLock.selection.piece["character"]).toEqual({ type: "unselectable" });
+  });
+
+  it("defaults to an empty schema/defaultMeta/values when no --json is given", async () => {
+    await runPieceMetaSet(["character", "--draft", draftPath]);
+
+    const meta = readDraftFile().stagedLock.pieceMeta["character"];
+    expect(meta).toEqual({ schema: {}, defaultMeta: {}, values: {} });
+  });
+
+  it("rejects per-piece values referencing a piece not in the roster", async () => {
+    const jsonPath = pathJoin(tempDir, "meta.json");
+    writeFileSync(jsonPath, JSON.stringify({
+      schema: { power: "number" },
+      defaultMeta: { power: 1 },
+      values: { "@author/missing": { power: 2 } },
+    }));
+
+    const { thrown } = await runPieceMetaSet(["character", "--draft", draftPath, "--json", jsonPath]);
+    expect(thrown).toBeUndefined(); // withErrorHandling swallows and sets exitCode instead
+    expect(process.exitCode).toBe(1);
+    process.exitCode = undefined;
+  });
+
+  it("rejects --json with an unrecognized field", async () => {
+    const jsonPath = pathJoin(tempDir, "bad-meta.json");
+    writeFileSync(jsonPath, JSON.stringify({ notARealField: true }));
+
+    await runPieceMetaSet(["character", "--draft", draftPath, "--json", jsonPath]);
+    expect(process.exitCode).toBe(1);
+    process.exitCode = undefined;
+  });
+
+  it("show prints the staged lock's piece meta", async () => {
+    const jsonPath = pathJoin(tempDir, "meta.json");
+    writeFileSync(jsonPath, JSON.stringify({ schema: { power: "number" }, defaultMeta: { power: 1 } }));
+    await runPieceMetaSet(["character", "--draft", draftPath, "--json", jsonPath]);
+
+    const { logs } = await runPieceMetaShow(["--draft", draftPath]);
+    const printed = JSON.parse(logs.join(""));
+    expect(printed["character"].schema).toEqual({ power: "number" });
+  });
+});

package/tests/commands/rescan.spec.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, readFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join as pathJoin } from "node:path";
+import { EMPTY_ROSTER_DRAFT } from "@roster-lock/shared";
+import { cloneJSON } from "@roster-lock/utils";
+import { RosterLockV1Draft } from "@roster-lock/types";
+
+async function runRescan(args: Array<string>){
+  vi.resetModules();
+  const { rescanCommand } = await import("../../src/commands/roster/rescan.js");
+
+  process.exitCode = undefined;
+  const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+  await rescanCommand.parseAsync(["node", "rescan", ...args]);
+  const logs = logSpy.mock.calls.map((call) => call.join(" "));
+  logSpy.mockRestore();
+  const exitCode = process.exitCode;
+  process.exitCode = undefined;
+  return { logs, exitCode };
+}
+
+describe("roster rescan", () => {
+  let tempDir: string;
+  let draftPath: string;
+  let pieceFolder: string;
+  let existingPiece: RosterLockV1Draft["stagedLock"]["rosters"][string][0];
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(pathJoin(tmpdir(), "rosterlock-rescan-"));
+    draftPath = pathJoin(tempDir, "test.rosterlock.draft.json");
+    pieceFolder = pathJoin(tempDir, "blue-character");
+    mkdirSync(pieceFolder);
+    writeFileSync(pathJoin(pieceFolder, "sprite.png"), "fake-png-bytes-v1");
+
+    const draft: RosterLockV1Draft = cloneJSON(EMPTY_ROSTER_DRAFT);
+    draft.stagedLock.engine.pieceDefinitions["character"] = {
+      selectionStrategy: "mandatory",
+      requires: ["move"],
+      pathVariables: [],
+      assets: [{ name: "sprite", classification: "media", count: 1, glob: ["*.png"] }],
+    };
+    draft.stagedLock.engine.pieceDefinitions["move"] = {
+      selectionStrategy: "on demand",
+      requires: [],
+      pathVariables: [],
+      assets: [],
+    };
+    draft.stagedLock.rosters["move"] = [{
+      id: "move-basic",
+      version: { logic: "d".repeat(64), media: "e".repeat(64), docs: "f".repeat(64) },
+      humanInfo: { name: "Basic", author: "author", url: "https://example.com/basic" },
+      downloadSources: ["https://example.com/basic.tar"],
+      pathVariables: {},
+      requiredPieces: {},
+    }];
+    existingPiece = {
+      id: "character-blue",
+      version: { logic: "a".repeat(64), media: "b".repeat(64), docs: "c".repeat(64) },
+      humanInfo: { name: "Blue", author: "author", url: "https://example.com/blue" },
+      downloadSources: ["https://example.com/blue.tar"],
+      pathVariables: {},
+      requiredPieces: { move: { selectable: true, expected: ["move-basic"] } },
+    };
+    draft.stagedLock.rosters["character"] = [existingPiece];
+    draft.draft.rosterPieceInfo["character"] = {
+      "character-blue": {
+        referenceFolder: pieceFolder,
+        testedDownloadSources: [
+          { source: "https://example.com/blue.tar", testedAt: Date.now(), version: existingPiece.version },
+        ],
+      },
+    };
+    writeFileSync(draftPath, JSON.stringify(draft));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  function readDraft(){
+    return JSON.parse(readFileSync(draftPath, "utf-8")) as RosterLockV1Draft;
+  }
+  function readPiece(){
+    return readDraft().stagedLock.rosters["character"][0];
+  }
+
+  it("recomputes the version hash using the recorded reference folder, keeping id/humanInfo/requiredPieces", async () => {
+    writeFileSync(pathJoin(pieceFolder, "sprite.png"), "fake-png-bytes-v2");
+
+    const { exitCode } = await runRescan(["character", "character-blue", "--draft", draftPath]);
+    expect(exitCode).toBeUndefined();
+
+    const piece = readPiece();
+    expect(piece.id).toBe("character-blue");
+    expect(piece.humanInfo).toEqual(existingPiece.humanInfo);
+    expect(piece.downloadSources).toEqual(existingPiece.downloadSources);
+    expect(piece.requiredPieces).toEqual({ move: { selectable: true, expected: ["move-basic"] } });
+    expect(piece.version.media).not.toBe("b".repeat(64));
+  });
+
+  it("resets testedDownloadSources for the piece since the hash changed", async () => {
+    writeFileSync(pathJoin(pieceFolder, "sprite.png"), "fake-png-bytes-v2");
+
+    await runRescan(["character", "character-blue", "--draft", draftPath]);
+
+    const draft = readDraft();
+    expect(draft.draft.rosterPieceInfo["character"]["character-blue"].testedDownloadSources).toEqual([]);
+  });
+
+  it("accepts an explicit folder argument overriding the recorded reference folder", async () => {
+    const otherFolder = pathJoin(tempDir, "other-folder");
+    mkdirSync(otherFolder);
+    writeFileSync(pathJoin(otherFolder, "sprite.png"), "different-bytes");
+
+    const { exitCode } = await runRescan(["character", "character-blue", otherFolder, "--draft", draftPath]);
+    expect(exitCode).toBeUndefined();
+
+    const draft = readDraft();
+    expect(draft.draft.rosterPieceInfo["character"]["character-blue"].referenceFolder).toBe(otherFolder);
+  });
+
+  it("fails when the folder no longer matches the piece type's asset definitions", async () => {
+    rmSync(pathJoin(pieceFolder, "sprite.png"));
+
+    const { exitCode } = await runRescan(["character", "character-blue", "--draft", draftPath]);
+    expect(exitCode).toBe(1);
+
+    const piece = readPiece();
+    expect(piece.version.media).toBe("b".repeat(64));
+  });
+
+  it("fails for an unknown piece id", async () => {
+    const { exitCode } = await runRescan(["character", "character-missing", "--draft", draftPath]);
+    expect(exitCode).toBe(1);
+  });
+});

package/tests/lib/draft-io.spec.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join as pathJoin } from "node:path";
+import { EMPTY_ROSTER_DRAFT } from "@roster-lock/shared";
+import { cloneJSON } from "@roster-lock/utils";
+import {
+  DRAFT_SUFFIX, resolveDraftPath, defaultDraftPath, readDraft, writeDraft,
+} from "../../src/lib/draft-io";
+
+describe("draft-io", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(pathJoin(tmpdir(), "rosterlock-draft-io-"));
+    vi.spyOn(process, "cwd").mockReturnValue(tempDir);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  describe("resolveDraftPath", () => {
+    it("resolves an explicit path against cwd", () => {
+      expect(resolveDraftPath("foo.rosterlock.draft.json")).toBe(pathJoin(tempDir, "foo.rosterlock.draft.json"));
+    });
+
+    it("finds the sole draft file in cwd", () => {
+      writeFileSync(pathJoin(tempDir, `only${DRAFT_SUFFIX}`), "{}");
+      expect(resolveDraftPath()).toBe(pathJoin(tempDir, `only${DRAFT_SUFFIX}`));
+    });
+
+    it("throws when no draft file is found", () => {
+      expect(() => resolveDraftPath()).toThrow(/No draft file found/);
+    });
+
+    it("throws when multiple draft files are found", () => {
+      writeFileSync(pathJoin(tempDir, `a${DRAFT_SUFFIX}`), "{}");
+      writeFileSync(pathJoin(tempDir, `b${DRAFT_SUFFIX}`), "{}");
+      expect(() => resolveDraftPath()).toThrow(/Multiple draft files found/);
+    });
+  });
+
+  describe("defaultDraftPath", () => {
+    it("slugifies the title", () => {
+      expect(defaultDraftPath("My Game")).toBe(pathJoin(tempDir, `my-game${DRAFT_SUFFIX}`));
+    });
+
+    it("falls back to 'config' when no usable title is given", () => {
+      expect(defaultDraftPath()).toBe(pathJoin(tempDir, `config${DRAFT_SUFFIX}`));
+      expect(defaultDraftPath("!!!")).toBe(pathJoin(tempDir, `config${DRAFT_SUFFIX}`));
+    });
+  });
+
+  describe("readDraft/writeDraft", () => {
+    it("round-trips a valid draft through cast + JSON", () => {
+      const draftPath = pathJoin(tempDir, `roundtrip${DRAFT_SUFFIX}`);
+      const draft = cloneJSON(EMPTY_ROSTER_DRAFT);
+      draft.stagedLock.title = "Test";
+
+      writeDraft(draftPath, draft);
+      const written = JSON.parse(readFileSync(draftPath, "utf-8"));
+      expect(written.stagedLock.title).toBe("Test");
+
+      const read = readDraft(draftPath);
+      expect(read.stagedLock.title).toBe("Test");
+    });
+
+    it("throws when reading an invalid draft", () => {
+      const draftPath = pathJoin(tempDir, `bad${DRAFT_SUFFIX}`);
+      writeFileSync(draftPath, JSON.stringify({ not: "a draft" }));
+      expect(() => readDraft(draftPath)).toThrow();
+    });
+  });
+});