@roster-lock/config-editor-cli 0.0.1

package/src/lib/schema-help.ts

@@ -0,0 +1,44 @@
+import { ZodType } from "zod";
+
+type ZodNode = { type: string, def: Record<string, unknown> };
+
+/**
+ * Renders a compact, human-readable sketch of a zod schema's shape (e.g.
+ * `{ name: string, count: number | "*" }`), for embedding in --help text so users
+ * know what a --json input needs to look like without reading source.
+ */
+export function describeSchemaShape(schema: ZodType): string {
+  return describe(schema as unknown as ZodNode);
+}
+
+function describe(node: ZodNode): string {
+  switch(node.type){
+    case "object": {
+      const shape = node.def.shape as Record<string, ZodNode>;
+      const parts = Object.entries(shape).map(([key, value]) => {
+        const isOptional = value.type === "optional";
+        const inner = isOptional ? (value.def.innerType as ZodNode) : value;
+        return `${key}${isOptional ? "?" : ""}: ${describe(inner)}`;
+      });
+      return `{ ${parts.join(", ")} }`;
+    }
+    case "array":
+      return `${describe(node.def.element as ZodNode)}[]`;
+    case "tuple":
+      return `[${(node.def.items as Array<ZodNode>).map(describe).join(", ")}]`;
+    case "union":
+      return (node.def.options as Array<ZodNode>).map(describe).join(" | ");
+    case "enum":
+      return Object.values(node.def.entries as Record<string, string>).map((v) => JSON.stringify(v)).join(" | ");
+    case "literal":
+      return (node.def.values as Array<unknown>).map((v) => JSON.stringify(v)).join(" | ");
+    case "record":
+      return `Record<${describe(node.def.keyType as ZodNode)}, ${describe(node.def.valueType as ZodNode)}>`;
+    case "optional":
+      return `${describe(node.def.innerType as ZodNode)}?`;
+    case "lazy":
+      return "<recursive>";
+    default:
+      return node.type;
+  }
+}

package/src/lib/schemas.ts

@@ -0,0 +1,100 @@
+import { z } from "zod";
+
+// Shape validation for JSON loaded via --json flags, before it's merged into the
+// staged lock. This is deliberately looser than the full lock schema in
+// @roster-lock/shared (AJV/JSON-schema, which also encodes cross-field domain
+// rules like requirement cycles or piece-meta consistency) - it exists to give a
+// fast, readable error for a malformed CLI argument, before that full check runs
+// against the whole staged lock.
+
+const countSchema = z.union([
+  z.number().int(),
+  z.literal("*"),
+  z.tuple([z.number().int(), z.union([z.number().int(), z.literal("*")])]),
+]);
+
+const assetSchema = z.object({
+  name: z.string(),
+  classification: z.enum(["logic", "media", "doc"]),
+  count: countSchema,
+  glob: z.array(z.string()),
+}).strict();
+
+export const pieceDefinitionSchema = z.object({
+  selectionStrategy: z.enum(["mandatory", "personal", "shared", "on demand"]),
+  requires: z.array(z.string()),
+  pathVariables: z.array(z.string()),
+  assets: z.array(assetSchema),
+}).strict();
+
+const pieceHumanInfoSchema = z.object({
+  name: z.string(),
+  author: z.string(),
+  url: z.string(),
+  image: z.string().optional(),
+}).strict();
+
+// Used by "roster add-piece"/"roster edit-piece" --json: an alternative to the
+// discrete --path-variables/--download-source/--name/etc flags. Only covers
+// additive fields (set humanInfo, add downloadSources/pathVariables) - removing a
+// download source or path variable still requires edit-piece's discrete flags.
+export const pieceOverridesSchema = z.object({
+  humanInfo: pieceHumanInfoSchema.optional(),
+  downloadSources: z.array(z.string()).optional(),
+  pathVariables: z.record(z.string(), z.string()).optional(),
+}).strict();
+
+const untrustedScriptRefSchema = z.object({
+  src: z.string(),
+  method: z.string().optional(),
+}).strict();
+
+const jsonShallowValueSchema = z.union([
+  z.string(), z.number(), z.boolean(),
+  z.array(z.string()), z.array(z.number()), z.array(z.boolean()),
+]);
+const jsonShallowObjectSchema = z.record(z.string(), jsonShallowValueSchema);
+
+// Used by "piece-meta set" --json: the top-level per-piece-type custom fields
+// (kept separate from the selection config so a selection config stays roster-agnostic).
+export const pieceMetaOverridesSchema = z.object({
+  schema: z.record(z.string(), z.enum(["boolean", "number", "string", "boolean[]", "number[]", "string[]"])).optional(),
+  defaultMeta: jsonShallowObjectSchema.optional(),
+  // Record<PieceId, Partial<Config>> - a record's values are already independently
+  // optional per key, so this is the same shape as the record itself.
+  values: z.record(z.string(), jsonShallowObjectSchema).optional(),
+}).strict();
+
+type SelectedPieceInput = {
+  id: string,
+  required: Record<string, { mandatory: Array<SelectedPieceInput>, selectable: Array<SelectedPieceInput> }>,
+};
+const selectedPieceSchema: z.ZodType<SelectedPieceInput> = z.lazy(() => z.object({
+  id: z.string(),
+  required: z.record(z.string(), z.object({
+    mandatory: z.array(selectedPieceSchema),
+    selectable: z.array(selectedPieceSchema),
+  }).strict()),
+}).strict());
+
+const userSelectionValidationSchema = z.object({
+  count: countSchema,
+  unique: z.boolean(),
+  banList: z.array(z.string()),
+  customValidation: z.array(untrustedScriptRefSchema),
+}).strict();
+
+// Keyed by the `--type` option on "selection set"; each schema covers the fields
+// mergeable on top of that type's template (its own template already supplies
+// `type`, so it stays optional here).
+export const selectionOverridesSchemas = {
+  normal: z.object({
+    validation: userSelectionValidationSchema.optional(),
+    mergeAlgorithm: untrustedScriptRefSchema.optional(),
+  }).strict(),
+  preselected: z.object({
+    pieces: z.array(selectedPieceSchema).optional(),
+  }).strict(),
+  unselectable: z.object({}).strict(),
+  "game-controlled": z.object({}).strict(),
+} as const;

package/src/lib/semver-report.ts

@@ -0,0 +1,11 @@
+import { SemVer } from "@roster-lock/shared";
+
+export function printSemverReasons(semver: SemVer): void {
+  const reasons = semver.getReasons();
+  for(const level of ["major", "minor", "patch"] as const){
+    for(const { reason, info } of reasons[level]){
+      console.log(`[${level}] ${reason} ${JSON.stringify(info)}`);
+    }
+  }
+  console.log(`Version: ${semver.toString()}`);
+}

package/src/lib/slugify.ts

@@ -0,0 +1,9 @@
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[\s_]+/g, '-')
+    .replace(/[^a-z0-9-]+/g, '')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-+/g, '-');
+}

package/test.rosterlock.draft.json

@@ -0,0 +1,62 @@
+{
+  "configIdentity": {
+    "namespace": "roster-lock",
+    "purpose": "draft",
+    "version": 1
+  },
+  "previousLock": {
+    "configIdentity": {
+      "namespace": "roster-lock",
+      "purpose": "lock",
+      "version": 1
+    },
+    "author": "",
+    "title": "",
+    "version": "0.0.0",
+    "engine": {
+      "name": "",
+      "version": "",
+      "pieceDefinitions": {}
+    },
+    "rosters": {},
+    "selection": {
+      "piece": {},
+      "globalValidation": [],
+      "scriptDictionary": {}
+    }
+  },
+  "stagedLock": {
+    "configIdentity": {
+      "namespace": "roster-lock",
+      "purpose": "lock",
+      "version": 1
+    },
+    "author": "",
+    "title": "Test Game",
+    "version": "0.0.0",
+    "engine": {
+      "name": "",
+      "version": "",
+      "pieceDefinitions": {
+        "character": {
+          "selectionStrategy": "mandatory",
+          "requires": [],
+          "pathVariables": [],
+          "assets": []
+        }
+      }
+    },
+    "rosters": {
+      "character": []
+    },
+    "selection": {
+      "piece": {},
+      "globalValidation": [],
+      "scriptDictionary": {}
+    }
+  },
+  "draft": {
+    "rosterPieceInfo": {},
+    "selectionScriptInfo": {}
+  }
+}

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

@@ -0,0 +1,92 @@
+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";
+
+// Repeatable options (--download-source) accumulate into a default array captured
+// once at `.option()`-declare time, so reusing one Command instance across
+// parseAsync() calls leaks values between tests - see edit-piece.spec.ts. Re-import
+// fresh for every call.
+async function runAddPiece(args: Array<string>){
+  vi.resetModules();
+  const { addPieceCommand } = await import("../../src/commands/roster/add-piece.js");
+
+  process.exitCode = undefined;
+  const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+  await addPieceCommand.parseAsync(["node", "add-piece", ...args]);
+  const logs = logSpy.mock.calls.map((call) => call.join(" "));
+  logSpy.mockRestore();
+  const exitCode = process.exitCode;
+  process.exitCode = undefined;
+  return { logs, exitCode };
+}
+
+describe("roster add-piece", () => {
+  let tempDir: string;
+  let draftPath: string;
+  let pieceFolder: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(pathJoin(tmpdir(), "rosterlock-add-piece-"));
+    draftPath = pathJoin(tempDir, "test.rosterlock.draft.json");
+    pieceFolder = pathJoin(tempDir, "blue-character");
+    mkdirSync(pieceFolder);
+    writeFileSync(pathJoin(pieceFolder, "sprite.png"), "fake-png-bytes");
+
+    const draft: RosterLockV1Draft = cloneJSON(EMPTY_ROSTER_DRAFT);
+    draft.stagedLock.engine.pieceDefinitions["character"] = {
+      selectionStrategy: "mandatory",
+      requires: [],
+      pathVariables: [],
+      assets: [{ name: "sprite", classification: "media", count: 1, glob: ["*.png"] }],
+    };
+    draft.stagedLock.rosters["character"] = [];
+    writeFileSync(draftPath, JSON.stringify(draft));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  function readPiece(){
+    const draft: RosterLockV1Draft = JSON.parse(readFileSync(draftPath, "utf-8"));
+    return draft.stagedLock.rosters["character"][0];
+  }
+
+  it("--json sets humanInfo and additional download sources", async () => {
+    const jsonPath = pathJoin(tempDir, "overrides.json");
+    writeFileSync(jsonPath, JSON.stringify({
+      humanInfo: { name: "Blue", author: "author", url: "https://example.com/blue" },
+      downloadSources: ["https://example.com/blue.tar"],
+    }));
+
+    await runAddPiece(["character", pieceFolder, "--draft", draftPath, "--json", jsonPath]);
+
+    const piece = readPiece();
+    expect(piece.humanInfo).toEqual({ name: "Blue", author: "author", url: "https://example.com/blue" });
+    expect(piece.downloadSources).toEqual(["https://example.com/blue.tar"]);
+    expect(piece.id).toBe("@author/blue");
+  });
+
+  it("still refuses to add a piece with no download source, --json or otherwise", async () => {
+    const jsonPath = pathJoin(tempDir, "overrides.json");
+    writeFileSync(jsonPath, JSON.stringify({ humanInfo: { name: "Blue", author: "author", url: "https://example.com/blue" } }));
+
+    const { exitCode } = await runAddPiece(["character", pieceFolder, "--draft", draftPath, "--json", jsonPath]);
+    expect(exitCode).toBe(1);
+  });
+
+  it("rejects --json with an unrecognized field", async () => {
+    const jsonPath = pathJoin(tempDir, "bad-overrides.json");
+    writeFileSync(jsonPath, JSON.stringify({ notARealField: true }));
+
+    const { exitCode } = await runAddPiece([
+      "character", pieceFolder, "--draft", draftPath, "--json", jsonPath,
+      "--download-source", "https://example.com/blue.tar",
+    ]);
+    expect(exitCode).toBe(1);
+  });
+});

package/tests/commands/draft-validate.spec.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } 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 { draftValidateCommand } from "../../src/commands/draft/validate";
+
+async function runValidate(draftPath: string){
+  const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+  const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+  process.exitCode = undefined;
+
+  await draftValidateCommand.parseAsync(["node", "draft-validate", "--draft", draftPath]);
+
+  const result = {
+    exitCode: process.exitCode,
+    logs: logSpy.mock.calls.map((call) => call.join(" ")),
+    errors: errorSpy.mock.calls.map((call) => call.join(" ")),
+  };
+  logSpy.mockRestore();
+  errorSpy.mockRestore();
+  process.exitCode = undefined;
+  return result;
+}
+
+describe("draft validate", () => {
+  let tempDir: string;
+  let draftPath: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(pathJoin(tmpdir(), "rosterlock-draft-validate-"));
+    draftPath = pathJoin(tempDir, "test.rosterlock.draft.json");
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  function writeDraftFixture(draft: RosterLockV1Draft){
+    writeFileSync(draftPath, JSON.stringify(draft));
+  }
+
+  it("reports OK and exit code 0 for a valid (empty) staged lock", async () => {
+    writeDraftFixture(cloneJSON(EMPTY_ROSTER_DRAFT));
+
+    const { exitCode, logs } = await runValidate(draftPath);
+
+    expect(exitCode).toBeUndefined();
+    expect(logs.join("\n")).toMatch(/OK/);
+  });
+
+  it("reports every issue at once for an invalid staged lock, not just the first", async () => {
+    const draft = cloneJSON(EMPTY_ROSTER_DRAFT);
+    draft.stagedLock.engine.pieceDefinitions["character"] = {
+      selectionStrategy: "mandatory",
+      requires: ["missing-type"],
+      pathVariables: [],
+      assets: [
+        { name: "sprite", classification: "media", count: 1, glob: ["*.png"] },
+        { name: "sprite", classification: "media", count: 1, glob: ["*.jpg"] },
+      ],
+    };
+    draft.stagedLock.rosters["character"] = [];
+    writeDraftFixture(draft);
+
+    const { exitCode, errors } = await runValidate(draftPath);
+    const output = errors.join("\n");
+
+    expect(exitCode).toBe(1);
+    // A single first-error-only validator would stop after the "requires" issue;
+    // both requirement AND duplicate-asset-name issues must be present together.
+    expect(output).toMatch(/missing-type/);
+    expect(output).toMatch(/Duplicate name/);
+    expect((output.match(/Duplicate name/g) ?? []).length).toBe(2);
+  });
+
+  it("propagates draft-resolution errors (e.g. missing draft file) via formatError", async () => {
+    const { exitCode, errors } = await runValidate(pathJoin(tempDir, "does-not-exist.rosterlock.draft.json"));
+
+    expect(exitCode).toBe(1);
+    expect(errors.join("\n")).toMatch(/ENOENT|no such file/i);
+  });
+});

package/tests/commands/edit-definition.spec.ts

@@ -0,0 +1,94 @@
+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 { editDefinitionCommand } from "../../src/commands/engine/edit-definition";
+
+async function runEditDefinition(args: Array<string>){
+  const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+  process.exitCode = undefined;
+  let thrown: unknown;
+  try {
+    await editDefinitionCommand.parseAsync(["node", "edit-definition", ...args]);
+  } catch(e){
+    thrown = e;
+  }
+  const logs = logSpy.mock.calls.map((call) => call.join(" "));
+  logSpy.mockRestore();
+  return { logs, thrown };
+}
+
+describe("engine edit-definition", () => {
+  let tempDir: string;
+  let draftPath: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(pathJoin(tmpdir(), "rosterlock-edit-definition-"));
+    draftPath = pathJoin(tempDir, "test.rosterlock.draft.json");
+
+    const draft: RosterLockV1Draft = cloneJSON(EMPTY_ROSTER_DRAFT);
+    draft.stagedLock.engine.pieceDefinitions["character"] = {
+      selectionStrategy: "mandatory",
+      requires: [],
+      pathVariables: [],
+      assets: [{ name: "sprite", classification: "media", count: 1, glob: ["*.png"] }],
+    };
+    draft.stagedLock.rosters["character"] = [];
+    writeFileSync(draftPath, JSON.stringify(draft));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  function readDraftFile(): RosterLockV1Draft {
+    return JSON.parse(readFileSync(draftPath, "utf-8"));
+  }
+
+  it("updates the selection strategy while leaving assets untouched", async () => {
+    await runEditDefinition(["character", "--draft", draftPath, "--strategy", "shared"]);
+
+    const definition = readDraftFile().stagedLock.engine.pieceDefinitions["character"];
+    expect(definition.selectionStrategy).toBe("shared");
+    expect(definition.assets).toHaveLength(1);
+  });
+
+  it("replaces the path-variables list", async () => {
+    await runEditDefinition(["character", "--draft", draftPath, "--path-variables", "region,skin"]);
+
+    const definition = readDraftFile().stagedLock.engine.pieceDefinitions["character"];
+    expect(definition.pathVariables).toEqual(["region", "skin"]);
+  });
+
+  it("rejects an unknown piece type", async () => {
+    const { thrown } = await runEditDefinition(["ghost", "--draft", draftPath, "--strategy", "shared"]);
+    expect(thrown).toBeUndefined(); // withErrorHandling swallows and sets exitCode instead
+    expect(process.exitCode).toBe(1);
+    process.exitCode = undefined;
+  });
+
+  it("rejects a no-op call with no flags given", async () => {
+    await runEditDefinition(["character", "--draft", draftPath]);
+    expect(process.exitCode).toBe(1);
+    process.exitCode = undefined;
+  });
+
+  it("--json replaces the full definition", async () => {
+    const jsonPath = pathJoin(tempDir, "def.json");
+    writeFileSync(jsonPath, JSON.stringify({
+      selectionStrategy: "personal",
+      requires: [],
+      pathVariables: [],
+      assets: [],
+    }));
+
+    await runEditDefinition(["character", "--draft", draftPath, "--json", jsonPath]);
+
+    const definition = readDraftFile().stagedLock.engine.pieceDefinitions["character"];
+    expect(definition.selectionStrategy).toBe("personal");
+    expect(definition.assets).toEqual([]);
+  });
+});

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

@@ -0,0 +1,153 @@
+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";
+
+// Repeatable options (--add-download-source etc.) accumulate into a default array
+// captured once at `.option()`-declare time, so reusing one Command instance across
+// parseAsync() calls leaks values between tests. A real CLI process only parses once,
+// so this only matters here: re-import the module fresh for every call to get a clean
+// Command instance and options.
+async function runEditPiece(args: Array<string>){
+  vi.resetModules();
+  const { editPieceCommand } = await import("../../src/commands/roster/edit-piece.js");
+
+  process.exitCode = undefined;
+  const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+  await editPieceCommand.parseAsync(["node", "edit-piece", ...args]);
+  const logs = logSpy.mock.calls.map((call) => call.join(" "));
+  logSpy.mockRestore();
+  const exitCode = process.exitCode;
+  process.exitCode = undefined;
+  return { logs, exitCode };
+}
+
+describe("roster edit-piece", () => {
+  let tempDir: string;
+  let draftPath: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(pathJoin(tmpdir(), "rosterlock-edit-piece-"));
+    draftPath = pathJoin(tempDir, "test.rosterlock.draft.json");
+
+    const draft: RosterLockV1Draft = cloneJSON(EMPTY_ROSTER_DRAFT);
+    draft.stagedLock.engine.pieceDefinitions["character"] = {
+      selectionStrategy: "mandatory",
+      requires: [],
+      pathVariables: ["skin"],
+      assets: [{ name: "sprite", classification: "media", count: 1, glob: ["{skin}/*.png"] }],
+    };
+    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: { skin: "blue" },
+      requiredPieces: {},
+    }];
+    writeFileSync(draftPath, JSON.stringify(draft));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  function readPiece(){
+    const draft: RosterLockV1Draft = JSON.parse(readFileSync(draftPath, "utf-8"));
+    return draft.stagedLock.rosters["character"][0];
+  }
+
+  it("updates human info fields", async () => {
+    await runEditPiece(["character", "@author/blue", "--draft", draftPath, "--name", "Bluey", "--author", "someone-else"]);
+
+    const piece = readPiece();
+    expect(piece.humanInfo.name).toBe("Bluey");
+    expect(piece.humanInfo.author).toBe("someone-else");
+    expect(piece.humanInfo.url).toBe("https://example.com/blue");
+  });
+
+  it("adds and removes download sources", async () => {
+    await runEditPiece([
+      "character", "@author/blue", "--draft", draftPath,
+      "--add-download-source", "https://mirror.example.com/blue.tar",
+      "--remove-download-source", "https://example.com/blue.tar",
+    ]);
+
+    const piece = readPiece();
+    expect(piece.downloadSources).toEqual(["https://mirror.example.com/blue.tar"]);
+  });
+
+  it("refuses to remove the last download source", async () => {
+    const { exitCode } = await runEditPiece([
+      "character", "@author/blue", "--draft", draftPath,
+      "--remove-download-source", "https://example.com/blue.tar",
+    ]);
+    expect(exitCode).toBe(1);
+  });
+
+  it("refuses to remove a download source that isn't present", async () => {
+    const { exitCode } = await runEditPiece([
+      "character", "@author/blue", "--draft", draftPath,
+      "--remove-download-source", "https://not-there.example.com/x.tar",
+    ]);
+    expect(exitCode).toBe(1);
+  });
+
+  it("updates path variables, leaving unmentioned keys alone", async () => {
+    await runEditPiece(["character", "@author/blue", "--draft", draftPath, "--path-variables", "skin=red"]);
+    expect(readPiece().pathVariables).toEqual({ skin: "red" });
+  });
+
+  it("rejects removing a path variable the piece definition still requires", async () => {
+    const { exitCode } = await runEditPiece([
+      "character", "@author/blue", "--draft", draftPath, "--remove-path-variable", "skin",
+    ]);
+    expect(exitCode).toBe(1);
+  });
+
+  it("rejects a no-op call", async () => {
+    const { exitCode } = await runEditPiece(["character", "@author/blue", "--draft", draftPath]);
+    expect(exitCode).toBe(1);
+  });
+
+  it("rejects an unknown piece id", async () => {
+    const { exitCode } = await runEditPiece(["character", "@author/ghost", "--draft", draftPath, "--name", "X"]);
+    expect(exitCode).toBe(1);
+  });
+
+  it("--json bulk-sets humanInfo/downloadSources/pathVariables", async () => {
+    const jsonPath = pathJoin(tempDir, "overrides.json");
+    writeFileSync(jsonPath, JSON.stringify({
+      humanInfo: { name: "Bluey", author: "someone-else", url: "https://example.com/bluey" },
+      downloadSources: ["https://mirror.example.com/blue.tar"],
+      pathVariables: { skin: "red" },
+    }));
+
+    await runEditPiece(["character", "@author/blue", "--draft", draftPath, "--json", jsonPath]);
+
+    const piece = readPiece();
+    expect(piece.humanInfo).toEqual({ name: "Bluey", author: "someone-else", url: "https://example.com/bluey" });
+    expect(piece.downloadSources).toEqual(["https://example.com/blue.tar", "https://mirror.example.com/blue.tar"]);
+    expect(piece.pathVariables).toEqual({ skin: "red" });
+  });
+
+  it("a specific flag overrides --json for the same field", async () => {
+    const jsonPath = pathJoin(tempDir, "overrides.json");
+    writeFileSync(jsonPath, JSON.stringify({ humanInfo: { name: "FromJson", author: "author", url: "https://example.com/blue" } }));
+
+    await runEditPiece(["character", "@author/blue", "--draft", draftPath, "--json", jsonPath, "--name", "FromFlag"]);
+
+    expect(readPiece().humanInfo.name).toBe("FromFlag");
+  });
+
+  it("rejects --json with an unrecognized field", async () => {
+    const jsonPath = pathJoin(tempDir, "bad-overrides.json");
+    writeFileSync(jsonPath, JSON.stringify({ notARealField: true }));
+
+    const { exitCode } = await runEditPiece(["character", "@author/blue", "--draft", draftPath, "--json", jsonPath]);
+    expect(exitCode).toBe(1);
+  });
+});