@roster-lock/config-editor-cli 0.0.1

package/src/commands/engine/edit-definition.ts

@@ -0,0 +1,58 @@
+import { Command } from "commander";
+import { ROSTERLOCK_V1_CASTER_JSONSCHEMA, validatePieceDefinition } from "@roster-lock/shared";
+import { RosterLockV1Config } from "@roster-lock/types";
+import { resolveDraftPath, readDraft, writeDraft } from "../../lib/draft-io";
+import { withDraftOption } from "../../lib/cli-options";
+import { withErrorHandling } from "../../lib/errors";
+import { parseCommaList, parseStrategy } from "../../lib/parse";
+import { readJsonInput } from "../../lib/json-input";
+import { pieceDefinitionSchema } from "../../lib/schemas";
+import { describeSchemaShape } from "../../lib/schema-help";
+
+type PieceDefinition = RosterLockV1Config["engine"]["pieceDefinitions"][string];
+
+export const editDefinitionCommand = withDraftOption(new Command("edit-definition"))
+  .description(
+    "Edit an existing piece type's selection strategy, requires, or path variables " +
+    "(use \"engine add-asset\"/\"remove-asset\" to change assets)"
+  )
+  .argument("<pieceType>", "the piece type key")
+  .option("--strategy <strategy>", "mandatory|personal|shared|on-demand")
+  .option("--requires <types>", "comma-separated list of required on-demand piece types (replaces the existing list)")
+  .option("--path-variables <names>", "comma-separated list of path variable names (replaces the existing list)")
+  .option(
+    "--json <file>",
+    "replace the full piece-type definition (including assets) from a JSON file (or \"-\" for stdin), instead of the flags above. " +
+    `Shape: ${describeSchemaShape(pieceDefinitionSchema)}`
+  )
+  .action(withErrorHandling(async (pieceType: string, opts: {
+    draft?: string, strategy?: string, requires?: string, pathVariables?: string, json?: string
+  }) => {
+    const draftPath = resolveDraftPath(opts.draft);
+    const draft = readDraft(draftPath);
+
+    const existing = draft.stagedLock.engine.pieceDefinitions[pieceType];
+    if(!existing) throw new Error(`Unknown piece type "${pieceType}"; define it first with "engine add-piece-type"`);
+
+    let definition: PieceDefinition;
+    if(opts.json){
+      definition = await readJsonInput(opts.json, pieceDefinitionSchema);
+    } else {
+      if(opts.strategy === undefined && opts.requires === undefined && opts.pathVariables === undefined){
+        throw new Error("Nothing to change; pass --strategy, --requires, --path-variables, or --json");
+      }
+      definition = {
+        ...existing,
+        selectionStrategy: opts.strategy !== undefined ? parseStrategy(opts.strategy) : existing.selectionStrategy,
+        requires: opts.requires !== undefined ? parseCommaList(opts.requires) : existing.requires,
+        pathVariables: opts.pathVariables !== undefined ? parseCommaList(opts.pathVariables) : existing.pathVariables,
+      };
+    }
+
+    draft.stagedLock.engine.pieceDefinitions[pieceType] = definition;
+    validatePieceDefinition(pieceType, definition, draft.stagedLock.engine);
+    ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(draft.stagedLock);
+
+    writeDraft(draftPath, draft);
+    console.log(`Updated piece type: ${pieceType}`);
+  }));

package/src/commands/engine/index.ts

@@ -0,0 +1,7 @@
+export * from "./set-info";
+export * from "./add-piece-type";
+export * from "./edit-definition";
+export * from "./add-asset";
+export * from "./remove-piece-type";
+export * from "./remove-asset";
+export * from "./show";

package/src/commands/engine/remove-asset.ts

@@ -0,0 +1,25 @@
+import { Command } from "commander";
+import { ROSTERLOCK_V1_CASTER_JSONSCHEMA } from "@roster-lock/shared";
+import { resolveDraftPath, readDraft, writeDraft } from "../../lib/draft-io";
+import { withDraftOption } from "../../lib/cli-options";
+import { withErrorHandling } from "../../lib/errors";
+
+export const removeAssetCommand = withDraftOption(new Command("remove-asset"))
+  .description("Remove an asset definition from a piece type")
+  .argument("<pieceType>", "the piece type key")
+  .argument("<assetName>", "the asset's name")
+  .action(withErrorHandling(async (pieceType: string, assetName: string, opts: { draft?: string }) => {
+    const draftPath = resolveDraftPath(opts.draft);
+    const draft = readDraft(draftPath);
+
+    const definition = draft.stagedLock.engine.pieceDefinitions[pieceType];
+    if(!definition) throw new Error(`Unknown piece type "${pieceType}"`);
+    const index = definition.assets.findIndex((a) => a.name === assetName);
+    if(index === -1) throw new Error(`Unknown asset "${assetName}" on piece type "${pieceType}"`);
+
+    definition.assets.splice(index, 1);
+    ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(draft.stagedLock);
+
+    writeDraft(draftPath, draft);
+    console.log(`Removed asset "${assetName}" from piece type "${pieceType}"`);
+  }));

package/src/commands/engine/remove-piece-type.ts

@@ -0,0 +1,27 @@
+import { Command } from "commander";
+import { ROSTERLOCK_V1_CASTER_JSONSCHEMA } from "@roster-lock/shared";
+import { resolveDraftPath, readDraft, writeDraft } from "../../lib/draft-io";
+import { withDraftOption } from "../../lib/cli-options";
+import { withErrorHandling } from "../../lib/errors";
+
+export const removePieceTypeCommand = withDraftOption(new Command("remove-piece-type"))
+  .description("Remove a piece type definition from the staged lock's engine")
+  .argument("<pieceType>", "the piece type key")
+  .action(withErrorHandling(async (pieceType: string, opts: { draft?: string }) => {
+    const draftPath = resolveDraftPath(opts.draft);
+    const draft = readDraft(draftPath);
+
+    if(!draft.stagedLock.engine.pieceDefinitions[pieceType]){
+      throw new Error(`Unknown piece type "${pieceType}"`);
+    }
+    const existingPieces = draft.stagedLock.rosters[pieceType];
+    if(existingPieces && existingPieces.length > 0){
+      throw new Error(`Piece type "${pieceType}" still has pieces in its roster; remove them first with "roster remove-piece"`);
+    }
+    delete draft.stagedLock.engine.pieceDefinitions[pieceType];
+    delete draft.stagedLock.rosters[pieceType];
+    ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(draft.stagedLock);
+
+    writeDraft(draftPath, draft);
+    console.log(`Removed piece type: ${pieceType}`);
+  }));

package/src/commands/engine/set-info.ts

@@ -0,0 +1,17 @@
+import { Command } from "commander";
+import { resolveDraftPath, readDraft, writeDraft } from "../../lib/draft-io";
+import { withDraftOption } from "../../lib/cli-options";
+import { withErrorHandling } from "../../lib/errors";
+
+export const setInfoCommand = withDraftOption(new Command("set-info"))
+  .description("Set the engine name/version on the staged lock")
+  .option("--name <name>", "engine name")
+  .option("--engine-version <version>", "engine version")
+  .action(withErrorHandling(async (opts: { draft?: string, name?: string, engineVersion?: string }) => {
+    const draftPath = resolveDraftPath(opts.draft);
+    const draft = readDraft(draftPath);
+    if(opts.name !== undefined) draft.stagedLock.engine.name = opts.name;
+    if(opts.engineVersion !== undefined) draft.stagedLock.engine.version = opts.engineVersion;
+    writeDraft(draftPath, draft);
+    console.log(`engine: ${draft.stagedLock.engine.name}@${draft.stagedLock.engine.version}`);
+  }));

package/src/commands/engine/show.ts

@@ -0,0 +1,20 @@
+import { Command } from "commander";
+import { resolveDraftPath, readDraft } from "../../lib/draft-io";
+import { withDraftOption } from "../../lib/cli-options";
+import { withErrorHandling } from "../../lib/errors";
+
+export const engineShowCommand = withDraftOption(new Command("show"))
+  .description("Print the staged lock's engine config, or a single piece type")
+  .argument("[pieceType]", "the piece type key (defaults to showing the whole engine config)")
+  .action(withErrorHandling(async (pieceType: string | undefined, opts: { draft?: string }) => {
+    const draftPath = resolveDraftPath(opts.draft);
+    const draft = readDraft(draftPath);
+
+    if(pieceType){
+      const definition = draft.stagedLock.engine.pieceDefinitions[pieceType];
+      if(!definition) throw new Error(`Unknown piece type "${pieceType}"`);
+      console.log(JSON.stringify(definition, null, 2));
+      return;
+    }
+    console.log(JSON.stringify(draft.stagedLock.engine, null, 2));
+  }));

package/src/commands/piece-meta/index.ts

@@ -0,0 +1,2 @@
+export * from "./set";
+export * from "./show";

package/src/commands/piece-meta/set.ts

@@ -0,0 +1,29 @@
+import { Command } from "commander";
+import { ROSTERLOCK_V1_CASTER_JSONSCHEMA, EMPTY_PIECE_META } from "@roster-lock/shared";
+import { cloneJSON } from "@roster-lock/utils";
+import { resolveDraftPath, readDraft, writeDraft } from "../../lib/draft-io";
+import { withDraftOption } from "../../lib/cli-options";
+import { withErrorHandling } from "../../lib/errors";
+import { readJsonInput } from "../../lib/json-input";
+import { pieceMetaOverridesSchema } from "../../lib/schemas";
+import { describeSchemaShape } from "../../lib/schema-help";
+
+export const pieceMetaSetCommand = withDraftOption(new Command("set"))
+  .description("Set the custom piece meta (schema/defaultMeta/values) for a piece type")
+  .argument("<pieceType>", "the piece type key")
+  .option(
+    "--json <file>",
+    "fields to merge in, read from a JSON file (or \"-\" for stdin). " +
+    `Shape: ${describeSchemaShape(pieceMetaOverridesSchema)}`
+  )
+  .action(withErrorHandling(async (pieceType: string, opts: { draft?: string, json?: string }) => {
+    const draftPath = resolveDraftPath(opts.draft);
+    const draft = readDraft(draftPath);
+
+    const overrides = opts.json ? await readJsonInput(opts.json, pieceMetaOverridesSchema) : {};
+    draft.stagedLock.pieceMeta[pieceType] = { ...cloneJSON(EMPTY_PIECE_META), ...overrides };
+
+    ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(draft.stagedLock);
+    writeDraft(draftPath, draft);
+    console.log(`Set piece meta for "${pieceType}"`);
+  }));

package/src/commands/piece-meta/show.ts

@@ -0,0 +1,12 @@
+import { Command } from "commander";
+import { resolveDraftPath, readDraft } from "../../lib/draft-io";
+import { withDraftOption } from "../../lib/cli-options";
+import { withErrorHandling } from "../../lib/errors";
+
+export const pieceMetaShowCommand = withDraftOption(new Command("show"))
+  .description("Print the staged lock's piece meta")
+  .action(withErrorHandling(async (opts: { draft?: string }) => {
+    const draftPath = resolveDraftPath(opts.draft);
+    const draft = readDraft(draftPath);
+    console.log(JSON.stringify(draft.stagedLock.pieceMeta, null, 2));
+  }));

package/src/commands/roster/add-piece.ts

@@ -0,0 +1,109 @@
+import { Command } from "commander";
+import { existsSync, readFileSync } from "node:fs";
+import { join as pathJoin } from "node:path";
+import {
+  ROSTERLOCK_V1_CASTER_JSONSCHEMA,
+  ROSTERLOCK_V1_PIECEINFO_CASTER_JSONSCHEMA,
+  PATH_ROSTERLOCK_PIECE_INFO,
+} from "@roster-lock/shared";
+import { RosterLockPiece } from "@roster-lock/types";
+import { resolveDraftPath, readDraft, writeDraft } from "../../lib/draft-io";
+import { withDraftOption } from "../../lib/cli-options";
+import { withErrorHandling } from "../../lib/errors";
+import { parseKeyValueList } from "../../lib/parse";
+import { scanPieceFolder } from "../../lib/piece-scan";
+import { slugify } from "../../lib/slugify";
+import { readJsonInput } from "../../lib/json-input";
+import { pieceOverridesSchema } from "../../lib/schemas";
+import { describeSchemaShape } from "../../lib/schema-help";
+
+function collectSource(value: string, previous: Array<string>){
+  previous.push(value);
+  return previous;
+}
+
+export const addPieceCommand = withDraftOption(new Command("add-piece"))
+  .description("Scan a folder and add it as a piece for an existing piece type")
+  .argument("<pieceType>", "the piece type key")
+  .argument("<folder>", "path to the folder to scan for the piece's assets")
+  .option("--path-variables <k=v,...>", "path variable values used to resolve this piece's asset globs")
+  .option("--download-source <url>", "download source url (repeatable)", collectSource, [] as Array<string>)
+  .option(
+    "--json <file>",
+    "set humanInfo/downloadSources/pathVariables from a JSON file (or \"-\" for stdin), applied on top of a " +
+    `rosterlock.piece-info.json in the folder if present. Shape: ${describeSchemaShape(pieceOverridesSchema)}`
+  )
+  .action(withErrorHandling(async (pieceType: string, folder: string, opts: {
+    draft?: string, pathVariables?: string, downloadSource: Array<string>, json?: string
+  }) => {
+    const draftPath = resolveDraftPath(opts.draft);
+    const draft = readDraft(draftPath);
+
+    const pieceDefinition = draft.stagedLock.engine.pieceDefinitions[pieceType];
+    if(!pieceDefinition) throw new Error(`Unknown piece type "${pieceType}"; define it first with "engine add-piece-type"`);
+
+    const pathVariables = parseKeyValueList(opts.pathVariables);
+    const { version, errors } = await scanPieceFolder(folder, pathVariables, pieceDefinition);
+    if(errors.length > 0){
+      for(const err of errors) console.error(`[${err.type}] ${err.id}: ${err.message}`);
+      throw new Error(`Folder does not match piece type "${pieceType}"'s asset definitions`);
+    }
+
+    const piece: RosterLockPiece = {
+      id: "",
+      version,
+      humanInfo: { name: "", author: "", url: "" },
+      downloadSources: [...opts.downloadSource],
+      pathVariables,
+      requiredPieces: Object.fromEntries(
+        pieceDefinition.requires.map((requiredType) => [requiredType, { selectable: false, expected: [] }])
+      ),
+    };
+
+    const metaPath = pathJoin(folder, PATH_ROSTERLOCK_PIECE_INFO);
+    if(existsSync(metaPath)){
+      const metaJson = JSON.parse(readFileSync(metaPath, "utf-8"));
+      const meta = ROSTERLOCK_V1_PIECEINFO_CASTER_JSONSCHEMA.cast(metaJson, true);
+      piece.humanInfo = meta.humanInfo;
+      for(const source of meta.downloadSources){
+        if(!piece.downloadSources.includes(source)) piece.downloadSources.push(source);
+      }
+    }
+
+    if(opts.json){
+      const overrides = await readJsonInput(opts.json, pieceOverridesSchema);
+      if(overrides.humanInfo) piece.humanInfo = overrides.humanInfo;
+      if(overrides.downloadSources){
+        for(const source of overrides.downloadSources){
+          if(!piece.downloadSources.includes(source)) piece.downloadSources.push(source);
+        }
+      }
+      if(overrides.pathVariables) Object.assign(piece.pathVariables, overrides.pathVariables);
+    }
+
+    if(piece.downloadSources.length === 0){
+      throw new Error(
+        "At least one download source is required; pass --download-source or provide a rosterlock.piece-info.json with downloadSources"
+      );
+    }
+
+    piece.id = piece.humanInfo.name
+      ? `@${slugify(piece.humanInfo.author)}/${slugify(piece.humanInfo.name)}`
+      : `#${version.logic}/${version.media}`;
+
+    const collection = draft.stagedLock.rosters[pieceType] ?? (draft.stagedLock.rosters[pieceType] = []);
+    if(collection.find((p) => p.id === piece.id)){
+      throw new Error(`Piece "${piece.id}" already exists in "${pieceType}"; use "roster remove-piece" first`);
+    }
+    collection.push(piece);
+    ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(draft.stagedLock);
+
+    draft.draft.rosterPieceInfo[pieceType] ??= {};
+    draft.draft.rosterPieceInfo[pieceType][piece.id] = {
+      referenceFolder: folder,
+      testedDownloadSources: [],
+    };
+
+    writeDraft(draftPath, draft);
+    console.log(`Added piece "${piece.id}" (logic=${version.logic}) to "${pieceType}"`);
+  }));

package/src/commands/roster/edit-piece.ts

@@ -0,0 +1,99 @@
+import { Command } from "commander";
+import { ROSTERLOCK_V1_CASTER_JSONSCHEMA } from "@roster-lock/shared";
+import { resolveDraftPath, readDraft, writeDraft } from "../../lib/draft-io";
+import { withDraftOption } from "../../lib/cli-options";
+import { withErrorHandling } from "../../lib/errors";
+import { parseKeyValueList } from "../../lib/parse";
+import { readJsonInput } from "../../lib/json-input";
+import { pieceOverridesSchema } from "../../lib/schemas";
+import { describeSchemaShape } from "../../lib/schema-help";
+
+function collect(value: string, previous: Array<string>){
+  previous.push(value);
+  return previous;
+}
+
+export const editPieceCommand = withDraftOption(new Command("edit-piece"))
+  .description("Edit an existing roster piece's human info, download sources, or path variables")
+  .argument("<pieceType>", "the piece type key")
+  .argument("<pieceId>", "the piece's id (as shown by \"roster list\")")
+  .option("--name <name>", "human-readable name")
+  .option("--author <author>", "author name")
+  .option("--url <url>", "info url")
+  .option("--image <url>", "image url")
+  .option("--add-download-source <url>", "download source url to add (repeatable)", collect, [] as Array<string>)
+  .option("--remove-download-source <url>", "download source url to remove (repeatable)", collect, [] as Array<string>)
+  .option("--path-variables <k=v,...>", "path variable values to set (existing keys not mentioned are left alone)")
+  .option("--remove-path-variable <name>", "path variable name to remove (repeatable)", collect, [] as Array<string>)
+  .option(
+    "--json <file>",
+    "bulk-set humanInfo/downloadSources/pathVariables from a JSON file (or \"-\" for stdin), applied before the " +
+    `flags above (so a specific flag always wins over --json). Shape: ${describeSchemaShape(pieceOverridesSchema)}`
+  )
+  .action(withErrorHandling(async (pieceType: string, pieceId: string, opts: {
+    draft?: string,
+    name?: string, author?: string, url?: string, image?: string,
+    addDownloadSource: Array<string>, removeDownloadSource: Array<string>,
+    pathVariables?: string, removePathVariable: Array<string>,
+    json?: string,
+  }) => {
+    const draftPath = resolveDraftPath(opts.draft);
+    const draft = readDraft(draftPath);
+
+    const collection = draft.stagedLock.rosters[pieceType];
+    if(!collection) throw new Error(`Unknown piece type "${pieceType}"`);
+    const piece = collection.find((p) => p.id === pieceId);
+    if(!piece) throw new Error(`Unknown piece "${pieceId}" in "${pieceType}"`);
+
+    const nothingRequested = (
+      opts.name === undefined && opts.author === undefined && opts.url === undefined && opts.image === undefined
+      && opts.addDownloadSource.length === 0 && opts.removeDownloadSource.length === 0
+      && opts.pathVariables === undefined && opts.removePathVariable.length === 0
+      && opts.json === undefined
+    );
+    if(nothingRequested){
+      throw new Error(
+        "Nothing to change; pass --name/--author/--url/--image, " +
+        "--add-download-source/--remove-download-source, --path-variables/--remove-path-variable, or --json"
+      );
+    }
+
+    if(opts.json){
+      const overrides = await readJsonInput(opts.json, pieceOverridesSchema);
+      if(overrides.humanInfo) piece.humanInfo = overrides.humanInfo;
+      if(overrides.downloadSources){
+        for(const source of overrides.downloadSources){
+          if(!piece.downloadSources.includes(source)) piece.downloadSources.push(source);
+        }
+      }
+      if(overrides.pathVariables) Object.assign(piece.pathVariables, overrides.pathVariables);
+    }
+
+    if(opts.name !== undefined) piece.humanInfo.name = opts.name;
+    if(opts.author !== undefined) piece.humanInfo.author = opts.author;
+    if(opts.url !== undefined) piece.humanInfo.url = opts.url;
+    if(opts.image !== undefined) piece.humanInfo.image = opts.image;
+
+    for(const source of opts.addDownloadSource){
+      if(!piece.downloadSources.includes(source)) piece.downloadSources.push(source);
+    }
+    for(const source of opts.removeDownloadSource){
+      const index = piece.downloadSources.indexOf(source);
+      if(index === -1) throw new Error(`Download source not found on piece "${pieceId}": ${source}`);
+      piece.downloadSources.splice(index, 1);
+    }
+    if(piece.downloadSources.length === 0){
+      throw new Error("A piece must keep at least one download source");
+    }
+
+    if(opts.pathVariables !== undefined){
+      Object.assign(piece.pathVariables, parseKeyValueList(opts.pathVariables));
+    }
+    for(const name of opts.removePathVariable){
+      delete piece.pathVariables[name];
+    }
+
+    ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(draft.stagedLock);
+    writeDraft(draftPath, draft);
+    console.log(`Updated piece "${pieceId}" in "${pieceType}"`);
+  }));

package/src/commands/roster/import-piece.ts

@@ -0,0 +1,112 @@
+import { Command } from "commander";
+import { resolve } from "node:path";
+import { ROSTERLOCK_V1_CASTER_JSONSCHEMA } from "@roster-lock/shared";
+import { cloneJSON } from "@roster-lock/utils";
+import { RosterLockPiece, RosterLockV1Config } from "@roster-lock/types";
+import { resolveDraftPath, readDraft, writeDraft, DRAFT_SUFFIX } from "../../lib/draft-io";
+import { readLock } from "../../lib/lock-io";
+import { withDraftOption } from "../../lib/cli-options";
+import { withErrorHandling } from "../../lib/errors";
+
+function readSourceConfig(sourcePath: string): RosterLockV1Config {
+  const resolved = resolve(process.cwd(), sourcePath);
+  if(resolved.endsWith(DRAFT_SUFFIX)) return readDraft(resolved).stagedLock;
+  return readLock(resolved);
+}
+
+function findByMatchingVersion(collection: Array<RosterLockPiece> | undefined, version: RosterLockPiece["version"]){
+  return collection?.find((p) => p.version.logic === version.logic && p.version.media === version.media);
+}
+
+// Pulls in whatever the piece needs so its requiredPieces.expected ids resolve in the target doc: reuse an
+// existing piece of matching logic/media version if one's already there (fixing up the expected id to match it),
+// otherwise copy the source piece over verbatim under its original id.
+function importRequiredPieces(
+  sourceConfig: RosterLockV1Config, targetConfig: RosterLockV1Config, piece: RosterLockPiece, importing: Set<string>
+){
+  for(const [requiredType, requirement] of Object.entries(piece.requiredPieces)){
+    requirement.expected = requirement.expected.map(
+      (requiredId) => importRequiredPiece(sourceConfig, targetConfig, requiredType, requiredId, importing)
+    );
+  }
+}
+
+function importRequiredPiece(
+  sourceConfig: RosterLockV1Config, targetConfig: RosterLockV1Config,
+  pieceType: string, sourceId: string, importing: Set<string>
+): string {
+  const sourcePiece = sourceConfig.rosters[pieceType]?.find((p) => p.id === sourceId);
+  if(!sourcePiece) throw new Error(`Required piece "${sourceId}" of type "${pieceType}" not found in the source document`);
+
+  const collection = targetConfig.rosters[pieceType] ?? (targetConfig.rosters[pieceType] = []);
+  const existing = findByMatchingVersion(collection, sourcePiece.version);
+  if(existing) return existing.id;
+
+  const importKey = `${pieceType}:${sourceId}`;
+  if(importing.has(importKey)){
+    throw new Error(`Circular required-piece reference detected at "${pieceType}" piece "${sourceId}"`);
+  }
+  if(collection.find((p) => p.id === sourceId)){
+    throw new Error(
+      `Cannot import required piece "${sourceId}" (${pieceType}): a different piece already exists under that id ` +
+      "in the target draft"
+    );
+  }
+
+  const requiredPiece = cloneJSON(sourcePiece);
+  collection.push(requiredPiece);
+
+  importing.add(importKey);
+  importRequiredPieces(sourceConfig, targetConfig, requiredPiece, importing);
+  importing.delete(importKey);
+
+  console.log(
+    `Imported required piece "${requiredPiece.id}" into "${pieceType}": ` +
+    `logic ${requiredPiece.version.logic}, media ${requiredPiece.version.media}`
+  );
+  return requiredPiece.id;
+}
+
+export const importPieceCommand = withDraftOption(new Command("import-piece"))
+  .description(
+    "Copy a piece from another draft or published lock file into this draft's rosters, trusting the source's " +
+    "existing hash as-is - use \"roster add-piece\" instead if you need the hash (re)computed from local files"
+  )
+  .argument("<sourcePath>", `path to the source draft (*${DRAFT_SUFFIX}) or published lock file`)
+  .argument("<pieceType>", "the piece type key (must exist in this draft's engine)")
+  .argument("<pieceId>", "the piece's id in the source (as shown by \"roster list\" run against the source)")
+  .option("--as <newId>", "import under a different piece id (defaults to the source piece's id)")
+  .action(withErrorHandling(async (sourcePath: string, pieceType: string, pieceId: string, opts: {
+    draft?: string, as?: string
+  }) => {
+    const draftPath = resolveDraftPath(opts.draft);
+    const draft = readDraft(draftPath);
+
+    const pieceDefinition = draft.stagedLock.engine.pieceDefinitions[pieceType];
+    if(!pieceDefinition) throw new Error(`Unknown piece type "${pieceType}"; define it first with "engine add-piece-type"`);
+
+    const sourceConfig = readSourceConfig(sourcePath);
+    const sourceCollection = sourceConfig.rosters[pieceType];
+    const sourcePiece = sourceCollection?.find((p) => p.id === pieceId);
+    if(!sourcePiece) throw new Error(`Unknown piece "${pieceId}" in "${pieceType}" in "${sourcePath}"`);
+
+    const newId = opts.as ?? sourcePiece.id;
+    const collection = draft.stagedLock.rosters[pieceType] ?? (draft.stagedLock.rosters[pieceType] = []);
+    if(collection.find((p) => p.id === newId)){
+      throw new Error(
+        `Piece "${newId}" already exists in "${pieceType}"; use --as to import under a different id, ` +
+        `or "roster remove-piece" first`
+      );
+    }
+
+    const piece: RosterLockPiece = { ...cloneJSON(sourcePiece), id: newId };
+    collection.push(piece);
+    importRequiredPieces(sourceConfig, draft.stagedLock, piece, new Set([`${pieceType}:${sourcePiece.id}`]));
+    ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(draft.stagedLock);
+
+    writeDraft(draftPath, draft);
+    console.log(
+      `Imported piece "${newId}"${newId !== sourcePiece.id ? ` (from "${sourcePiece.id}")` : ""} into "${pieceType}": ` +
+      `logic ${piece.version.logic}, media ${piece.version.media}`
+    );
+  }));

package/src/commands/roster/index.ts

@@ -0,0 +1,7 @@
+export * from "./add-piece";
+export * from "./edit-piece";
+export * from "./import-piece";
+export * from "./rescan";
+export * from "./test-download";
+export * from "./list";
+export * from "./remove-piece";

package/src/commands/roster/list.ts

@@ -0,0 +1,23 @@
+import { Command } from "commander";
+import { resolveDraftPath, readDraft } from "../../lib/draft-io";
+import { withDraftOption } from "../../lib/cli-options";
+import { withErrorHandling } from "../../lib/errors";
+
+export const rosterListCommand = withDraftOption(new Command("list"))
+  .description("List pieces in the staged lock's rosters")
+  .argument("[pieceType]", "the piece type key (defaults to listing every piece type's roster)")
+  .action(withErrorHandling(async (pieceType: string | undefined, opts: { draft?: string }) => {
+    const draftPath = resolveDraftPath(opts.draft);
+    const draft = readDraft(draftPath);
+
+    const collections = pieceType
+      ? { [pieceType]: draft.stagedLock.rosters[pieceType] ?? [] }
+      : draft.stagedLock.rosters;
+
+    for(const [type, pieces] of Object.entries(collections)){
+      console.log(`${type}:`);
+      for(const piece of pieces){
+        console.log(`  ${piece.id}  logic=${piece.version.logic.slice(0, 12)}  sources=${piece.downloadSources.length}`);
+      }
+    }
+  }));

package/src/commands/roster/remove-piece.ts

@@ -0,0 +1,28 @@
+import { Command } from "commander";
+import { ROSTERLOCK_V1_CASTER_JSONSCHEMA } from "@roster-lock/shared";
+import { resolveDraftPath, readDraft, writeDraft } from "../../lib/draft-io";
+import { withDraftOption } from "../../lib/cli-options";
+import { withErrorHandling } from "../../lib/errors";
+
+export const removePieceCommand = withDraftOption(new Command("remove-piece"))
+  .description("Remove a piece from the staged lock's rosters")
+  .argument("<pieceType>", "the piece type key")
+  .argument("<pieceId>", "the piece's id (as shown by \"roster list\")")
+  .action(withErrorHandling(async (pieceType: string, pieceId: string, opts: { draft?: string }) => {
+    const draftPath = resolveDraftPath(opts.draft);
+    const draft = readDraft(draftPath);
+
+    const collection = draft.stagedLock.rosters[pieceType];
+    if(!collection) throw new Error(`Unknown piece type "${pieceType}"`);
+    const index = collection.findIndex((p) => p.id === pieceId);
+    if(index === -1) throw new Error(`Unknown piece "${pieceId}" in "${pieceType}"`);
+
+    collection.splice(index, 1);
+    ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(draft.stagedLock);
+
+    const pieceInfo = draft.draft.rosterPieceInfo[pieceType];
+    if(pieceInfo) delete pieceInfo[pieceId];
+
+    writeDraft(draftPath, draft);
+    console.log(`Removed piece "${pieceId}" from "${pieceType}"`);
+  }));