@roster-lock/config-editor-cli 0.0.1

package/src/commands/roster/rescan.ts

@@ -0,0 +1,63 @@
+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 { scanPieceFolder } from "../../lib/piece-scan";
+
+export const rescanCommand = withDraftOption(new Command("rescan"))
+  .description(
+    "Recompute an existing roster piece's asset hashes from its folder (e.g. after adding new asset files or " +
+    "changing an asset definition), without touching its id, humanInfo, downloadSources, or requiredPieces"
+  )
+  .argument("<pieceType>", "the piece type key")
+  .argument("<pieceId>", "the piece's id (as shown by \"roster list\")")
+  .argument("[folder]", "path to the folder to scan (defaults to the folder used by the last \"roster add-piece\"/\"roster rescan\")")
+  .option("--path-variables <k=v,...>", "path variable values used to resolve this piece's asset globs (defaults to the piece's existing path variables)")
+  .action(withErrorHandling(async (pieceType: string, pieceId: string, folderArg: string | undefined, opts: {
+    draft?: string, pathVariables?: 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}"`);
+
+    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 pieceInfo = draft.draft.rosterPieceInfo[pieceType]?.[pieceId];
+    const folder = folderArg ?? pieceInfo?.referenceFolder;
+    if(!folder){
+      throw new Error(
+        `No folder recorded for piece "${pieceId}"; pass one explicitly: ` +
+        `roster rescan ${pieceType} ${pieceId} <folder>`
+      );
+    }
+
+    const pathVariables = opts.pathVariables !== undefined ? parseKeyValueList(opts.pathVariables) : piece.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 oldVersion = piece.version;
+    piece.version = version;
+    ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(draft.stagedLock);
+
+    draft.draft.rosterPieceInfo[pieceType] ??= {};
+    draft.draft.rosterPieceInfo[pieceType][pieceId] = {
+      referenceFolder: folder,
+      testedDownloadSources: [],
+    };
+
+    writeDraft(draftPath, draft);
+    console.log(
+      `Rescanned piece "${pieceId}" in "${pieceType}": ` +
+      `logic ${oldVersion.logic}->${version.logic}, media ${oldVersion.media}->${version.media}, docs ${oldVersion.docs}->${version.docs}`
+    );
+  }));

package/src/commands/roster/test-download.ts

@@ -0,0 +1,76 @@
+import { Command } from "commander";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join as pathJoin } from "node:path";
+import { downloadToFolder, DEFAULT_PLUGIN_DIR } from "@roster-lock/plugin-runtime";
+import { resolveDraftPath, readDraft, writeDraft } from "../../lib/draft-io";
+import { withDraftOption } from "../../lib/cli-options";
+import { withErrorHandling } from "../../lib/errors";
+import { scanPieceFolder } from "../../lib/piece-scan";
+
+export const testDownloadCommand = withDraftOption(new Command("test-download"))
+  .description("Download a source over the network, verify its hash matches the piece, and record the test")
+  .argument("<pieceType>", "the piece type key")
+  .argument("<pieceId>", "the piece's id (as shown by \"roster list\")")
+  .argument("<sourceUrl>", "download source url to fetch and verify")
+  .action(withErrorHandling(async (pieceType: string, pieceId: string, sourceUrl: string, opts: { draft?: 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}"`);
+    const piece = draft.stagedLock.rosters[pieceType]?.find((p) => p.id === pieceId);
+    if(!piece) throw new Error(`Unknown piece "${pieceId}" in "${pieceType}"`);
+
+    const tempDir = await mkdtemp(pathJoin(tmpdir(), "rosterlock-test-download-"));
+    try {
+      const { finishPromise } = await downloadToFolder(DEFAULT_PLUGIN_DIR, {
+        url: sourceUrl,
+        destinationFolder: tempDir,
+        processHandlers: {
+          abortSignal: new AbortController().signal,
+          onProgress: (progress, total) => {
+            process.stderr.write(`\rDownloading... ${progress}${total ? `/${total}` : ""}`);
+          },
+        },
+      });
+      await finishPromise;
+      process.stderr.write("\n");
+
+      const { version, errors } = await scanPieceFolder(tempDir, piece.pathVariables, pieceDefinition);
+      if(errors.length > 0){
+        for(const err of errors) console.error(`[${err.type}] ${err.id}: ${err.message}`);
+        throw new Error("Downloaded folder does not match the piece type's asset definitions");
+      }
+
+      if(
+        version.logic !== piece.version.logic ||
+        version.media !== piece.version.media ||
+        version.docs !== piece.version.docs
+      ){
+        console.error("Version mismatch:");
+        console.error(`  expected: ${JSON.stringify(piece.version)}`);
+        console.error(`  actual:   ${JSON.stringify(version)}`);
+        throw new Error(`Downloaded source does not match the recorded version for "${pieceId}"`);
+      }
+
+      if(!piece.downloadSources.includes(sourceUrl)){
+        piece.downloadSources.push(sourceUrl);
+      }
+
+      draft.draft.rosterPieceInfo[pieceType] ??= {};
+      const pieceInfo = draft.draft.rosterPieceInfo[pieceType][pieceId] ?? (
+        draft.draft.rosterPieceInfo[pieceType][pieceId] = { testedDownloadSources: [] }
+      );
+      pieceInfo.testedDownloadSources.push({
+        source: sourceUrl,
+        testedAt: Date.now(),
+        version,
+      });
+
+      writeDraft(draftPath, draft);
+      console.log(`Verified download source for "${pieceId}"`);
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  }));

package/src/commands/selection/add-script.ts

@@ -0,0 +1,44 @@
+import { Command } from "commander";
+import { statSync, readFileSync } from "node:fs";
+import { resolve, basename } from "node:path";
+import { bufferToStr, createShaFromBuffer } from "@roster-lock/utils";
+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 { walkRelative } from "../../lib/fs-walk";
+
+export const addScriptCommand = withDraftOption(new Command("add-script"))
+  .description("Add one or more selection scripts (a single file, or every file in a folder) to the staged lock")
+  .argument("<fileOrFolder>", "path to a single script file, or a folder of script files")
+  .option("--key <relPath>", "script key to use when adding a single file (defaults to its basename)")
+  .action(withErrorHandling(async (fileOrFolder: string, opts: { draft?: string, key?: string }) => {
+    const draftPath = resolveDraftPath(opts.draft);
+    const draft = readDraft(draftPath);
+
+    const target = resolve(process.cwd(), fileOrFolder);
+    const stats = statSync(target);
+    const lastLoad = Date.now();
+
+    const entries: Array<{ key: string, absolutePath: string }> = [];
+    if(stats.isDirectory()){
+      for await (const relativePath of walkRelative(target)){
+        entries.push({ key: relativePath, absolutePath: resolve(target, relativePath) });
+      }
+    } else {
+      entries.push({ key: opts.key ?? basename(target), absolutePath: target });
+    }
+
+    for(const { key, absolutePath } of entries){
+      const contentRaw = readFileSync(absolutePath);
+      const content = bufferToStr(contentRaw);
+      const sha = await createShaFromBuffer(contentRaw);
+
+      draft.stagedLock.selection.scriptDictionary[key] = { content };
+      draft.draft.selectionScriptInfo[key] = { lastLoad, sha, referencePath: absolutePath };
+    }
+
+    ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(draft.stagedLock);
+    writeDraft(draftPath, draft);
+    console.log(`Added ${entries.length} script(s): ${entries.map((e) => e.key).join(", ")}`);
+  }));

package/src/commands/selection/index.ts

@@ -0,0 +1,4 @@
+export * from "./add-script";
+export * from "./set";
+export * from "./run-script";
+export * from "./show";

package/src/commands/selection/run-script.ts

@@ -0,0 +1,30 @@
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { runUntrustedScript, DEFAULT_PLUGIN_DIR } from "@roster-lock/plugin-runtime";
+import { ScriptPurposeInput } from "@roster-lock/types";
+import { resolveDraftPath, readDraft } from "../../lib/draft-io";
+import { withDraftOption } from "../../lib/cli-options";
+import { withErrorHandling } from "../../lib/errors";
+
+export const runScriptCommand = withDraftOption(new Command("run-script"))
+  .description("Run a selection script from the staged lock against sample input, without modifying the draft")
+  .argument("<scriptRef>", "the script's key in scriptDictionary")
+  .requiredOption("--input <jsonFile>", "JSON file with { purpose: ScriptPurposeInput, randomSeeds?: string[] }")
+  .option("--method <name>", "exported function to call (default: main)")
+  .action(withErrorHandling(async (scriptRef: string, opts: { draft?: string, input: string, method?: string }) => {
+    const draftPath = resolveDraftPath(opts.draft);
+    const draft = readDraft(draftPath);
+
+    const input = JSON.parse(readFileSync(opts.input, "utf-8")) as {
+      purpose: ScriptPurposeInput, randomSeeds?: Array<string>
+    };
+
+    const result = await runUntrustedScript(DEFAULT_PLUGIN_DIR, {
+      config: draft.stagedLock,
+      randomSeeds: input.randomSeeds ?? [],
+      purpose: input.purpose,
+      entryScript: { src: scriptRef, method: opts.method },
+    });
+
+    console.log(JSON.stringify(result, null, 2));
+  }));

package/src/commands/selection/set.ts

@@ -0,0 +1,54 @@
+import { Command } from "commander";
+import { ZodType } from "zod";
+import {
+  ROSTERLOCK_V1_CASTER_JSONSCHEMA,
+  EMPTY_ROSTER_NORMAL_SELECTION,
+  EMPTY_ROSTER_PRESELECTED_SELECTION,
+  EMPTY_ROSTER_UNSELECTABLE_SELECTION,
+  EMPTY_ROSTER_GAME_SELECTION,
+} 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 { selectionOverridesSchemas } from "../../lib/schemas";
+import { describeSchemaShape } from "../../lib/schema-help";
+
+const TEMPLATES = {
+  normal: EMPTY_ROSTER_NORMAL_SELECTION,
+  preselected: EMPTY_ROSTER_PRESELECTED_SELECTION,
+  unselectable: EMPTY_ROSTER_UNSELECTABLE_SELECTION,
+  "game-controlled": EMPTY_ROSTER_GAME_SELECTION,
+} as const;
+
+const JSON_SHAPE_BY_TYPE = Object.entries(selectionOverridesSchemas)
+  .map(([type, schema]) => `${type}: ${describeSchemaShape(schema)}`)
+  .join("; ");
+
+export const selectionSetCommand = withDraftOption(new Command("set"))
+  .description("Set the selection config for a piece type")
+  .argument("<pieceType>", "the piece type key")
+  .requiredOption("--type <type>", "normal|preselected|unselectable|game-controlled")
+  .option(
+    "--json <file>",
+    "type-specific fields to merge in, read from a JSON file (or \"-\" for stdin); shape depends on --type. " +
+    `Shapes: ${JSON_SHAPE_BY_TYPE}`
+  )
+  .action(withErrorHandling(async (pieceType: string, opts: { draft?: string, type: string, json?: string }) => {
+    const draftPath = resolveDraftPath(opts.draft);
+    const draft = readDraft(draftPath);
+
+    const template = TEMPLATES[opts.type as keyof typeof TEMPLATES];
+    if(!template) throw new Error(`Invalid --type "${opts.type}" (expected normal|preselected|unselectable|game-controlled)`);
+
+    const overridesSchema = selectionOverridesSchemas[opts.type as keyof typeof selectionOverridesSchemas] as (
+      ZodType<Record<string, unknown>>
+    );
+    const overrides = opts.json ? await readJsonInput(opts.json, overridesSchema) : {};
+    draft.stagedLock.selection.piece[pieceType] = { ...cloneJSON(template), ...overrides };
+
+    ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(draft.stagedLock);
+    writeDraft(draftPath, draft);
+    console.log(`Set selection for "${pieceType}" to "${opts.type}"`);
+  }));

package/src/commands/selection/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 selectionShowCommand = withDraftOption(new Command("show"))
+  .description("Print the staged lock's selection config")
+  .action(withErrorHandling(async (opts: { draft?: string }) => {
+    const draftPath = resolveDraftPath(opts.draft);
+    const draft = readDraft(draftPath);
+    console.log(JSON.stringify(draft.stagedLock.selection, null, 2));
+  }));

package/src/commands/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 showCommand = withDraftOption(new Command("show"))
+  .description("Print the draft's full staged lock as JSON")
+  .action(withErrorHandling(async (opts: { draft?: string }) => {
+    const draftPath = resolveDraftPath(opts.draft);
+    const draft = readDraft(draftPath);
+    console.log(JSON.stringify(draft.stagedLock, null, 2));
+  }));

package/src/commands/validate.ts

@@ -0,0 +1,26 @@
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { ROSTERLOCK_V1_DRAFT_CASTER_JSONSCHEMA, ROSTERLOCK_V1_CASTER_JSONSCHEMA } from "@roster-lock/shared";
+import { resolveDraftPath } from "../lib/draft-io";
+import { withDraftOption } from "../lib/cli-options";
+import { formatError } from "../lib/errors";
+
+export const validateCommand = withDraftOption(new Command("validate"))
+  .description("Validate a draft (default) or, with --lock, a published lock file")
+  .option("--lock <path>", "validate a plain lock file instead of a draft")
+  .action(async (opts: { draft?: string, lock?: string }) => {
+    try {
+      if(opts.lock){
+        const json = JSON.parse(readFileSync(opts.lock, "utf-8"));
+        ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(json, true);
+      } else {
+        const draftPath = resolveDraftPath(opts.draft);
+        const json = JSON.parse(readFileSync(draftPath, "utf-8"));
+        ROSTERLOCK_V1_DRAFT_CASTER_JSONSCHEMA.cast(json, true);
+      }
+      console.log("OK");
+    } catch(e){
+      console.error(formatError(e));
+      process.exitCode = 1;
+    }
+  });

package/src/index.ts

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+import { program, Command } from "commander";
+
+import { initCommand, fromLockCommand, promoteCommand, publishCommand, draftValidateCommand } from "./commands/draft";
+import {
+  setInfoCommand,
+  addPieceTypeCommand,
+  editDefinitionCommand,
+  addAssetCommand,
+  removePieceTypeCommand,
+  removeAssetCommand,
+  engineShowCommand,
+} from "./commands/engine";
+import {
+  addPieceCommand,
+  editPieceCommand,
+  importPieceCommand,
+  rescanCommand,
+  testDownloadCommand,
+  rosterListCommand,
+  removePieceCommand,
+} from "./commands/roster";
+import {
+  addScriptCommand,
+  selectionSetCommand,
+  runScriptCommand,
+  selectionShowCommand,
+} from "./commands/selection";
+import {
+  pieceMetaSetCommand,
+  pieceMetaShowCommand,
+} from "./commands/piece-meta";
+import { validateCommand } from "./commands/validate";
+import { showCommand } from "./commands/show";
+import { VERSION } from "./version";
+
+program
+  .name("rosterlock-config-editor")
+  .description("A cli tool to build roster lock configs")
+  .version(VERSION);
+
+const draftCommand = new Command("draft").description("Manage the draft lifecycle (create, promote, publish, validate)");
+draftCommand.addCommand(initCommand);
+draftCommand.addCommand(fromLockCommand);
+draftCommand.addCommand(promoteCommand);
+draftCommand.addCommand(publishCommand);
+draftCommand.addCommand(draftValidateCommand);
+program.addCommand(draftCommand);
+
+program.addCommand(validateCommand);
+program.addCommand(showCommand);
+
+const engineCommand = new Command("engine").description("Edit the staged lock's engine (piece types)");
+engineCommand.addCommand(setInfoCommand);
+engineCommand.addCommand(addPieceTypeCommand);
+engineCommand.addCommand(editDefinitionCommand);
+engineCommand.addCommand(addAssetCommand);
+engineCommand.addCommand(removePieceTypeCommand);
+engineCommand.addCommand(removeAssetCommand);
+engineCommand.addCommand(engineShowCommand);
+program.addCommand(engineCommand);
+
+const rosterCommand = new Command("roster").description("Edit the staged lock's rosters (pieces)");
+rosterCommand.addCommand(addPieceCommand);
+rosterCommand.addCommand(editPieceCommand);
+rosterCommand.addCommand(importPieceCommand);
+rosterCommand.addCommand(rescanCommand);
+rosterCommand.addCommand(testDownloadCommand);
+rosterCommand.addCommand(rosterListCommand);
+rosterCommand.addCommand(removePieceCommand);
+program.addCommand(rosterCommand);
+
+const selectionCommand = new Command("selection").description("Edit the staged lock's selection config");
+selectionCommand.addCommand(addScriptCommand);
+selectionCommand.addCommand(selectionSetCommand);
+selectionCommand.addCommand(runScriptCommand);
+selectionCommand.addCommand(selectionShowCommand);
+program.addCommand(selectionCommand);
+
+const pieceMetaCommand = new Command("piece-meta").description("Edit the staged lock's piece meta (custom per-piece fields)");
+pieceMetaCommand.addCommand(pieceMetaSetCommand);
+pieceMetaCommand.addCommand(pieceMetaShowCommand);
+program.addCommand(pieceMetaCommand);
+
+program.parse();

package/src/lib/cli-options.ts

@@ -0,0 +1,8 @@
+import { Command } from "commander";
+
+export function withDraftOption(cmd: Command): Command {
+  return cmd.option(
+    "-d, --draft <path>",
+    "path to the draft file (defaults to the sole *.rosterlock.draft.json file in the current directory)"
+  );
+}

package/src/lib/draft-io.ts

@@ -0,0 +1,41 @@
+import { readFileSync, writeFileSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { ROSTERLOCK_V1_DRAFT_CASTER_JSONSCHEMA } from "@roster-lock/shared";
+import { RosterLockV1Draft } from "@roster-lock/types";
+import { slugify } from "./slugify";
+
+export const DRAFT_SUFFIX = ".rosterlock.draft.json";
+
+export function resolveDraftPath(explicit?: string): string {
+  if(explicit) return resolve(process.cwd(), explicit);
+
+  const cwd = process.cwd();
+  const candidates = readdirSync(cwd).filter((name) => name.endsWith(DRAFT_SUFFIX));
+
+  if(candidates.length === 0){
+    throw new Error(
+      `No draft file found in current directory (expected a *${DRAFT_SUFFIX} file); pass --draft <path>`
+    );
+  }
+  if(candidates.length > 1){
+    throw new Error(
+      `Multiple draft files found in current directory: ${candidates.join(", ")}; pass --draft <path> to choose one`
+    );
+  }
+  return resolve(cwd, candidates[0]);
+}
+
+export function defaultDraftPath(title?: string): string {
+  const slug = slugify(title && title.length > 0 ? title : "config") || "config";
+  return resolve(process.cwd(), `${slug}${DRAFT_SUFFIX}`);
+}
+
+export function readDraft(path: string): RosterLockV1Draft {
+  const json = JSON.parse(readFileSync(path, "utf-8"));
+  return ROSTERLOCK_V1_DRAFT_CASTER_JSONSCHEMA.cast(json, true);
+}
+
+export function writeDraft(path: string, draft: RosterLockV1Draft): void {
+  ROSTERLOCK_V1_DRAFT_CASTER_JSONSCHEMA.cast(draft, true);
+  writeFileSync(path, JSON.stringify(draft, null, 2) + "\n");
+}

package/src/lib/errors.ts

@@ -0,0 +1,30 @@
+import { ErrorObject } from "ajv";
+import { ZodError } from "zod";
+
+export function formatError(e: unknown): string {
+  if(e instanceof ZodError){
+    return e.issues
+      .map((issue) => `/${issue.path.join("/")} ${issue.message}`)
+      .join("\n");
+  }
+  if(Array.isArray(e)){
+    return (e as Array<ErrorObject>)
+      .map((err) => `${err.instancePath || "/"} ${err.message}`)
+      .join("\n");
+  }
+  if(e instanceof Error) return e.message;
+  return String(e);
+}
+
+export function withErrorHandling<Args extends Array<any>>(
+  fn: (...args: Args) => Promise<void>
+) {
+  return async (...args: Args) => {
+    try {
+      await fn(...args);
+    } catch(e){
+      console.error(formatError(e));
+      process.exitCode = 1;
+    }
+  };
+}

package/src/lib/fs-walk.ts

@@ -0,0 +1,31 @@
+import { readdir, stat as fsStat } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { join as pathJoin, relative as pathRelative, sep as pathSep } from "node:path";
+
+/**
+ * Yields file paths relative to `root`, using forward slashes, matching the
+ * convention `getMatchingAssetsForFile` expects for glob matching.
+ */
+export async function* walkRelative(root: string): AsyncIterable<string> {
+  yield* walk(root, root);
+}
+
+async function* walk(root: string, dir: string): AsyncIterable<string> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for(const entry of entries){
+    const fullPath = pathJoin(dir, entry.name);
+    if(entry.isDirectory()){
+      yield* walk(root, fullPath);
+    } else {
+      yield pathRelative(root, fullPath).split(pathSep).join("/");
+    }
+  }
+}
+
+export async function getFileFromRoot(
+  root: string, relativePath: string
+): Promise<{ byteSize: number, stream: AsyncIterable<Uint8Array> }> {
+  const fullPath = pathJoin(root, relativePath);
+  const stats = await fsStat(fullPath);
+  return { byteSize: stats.size, stream: createReadStream(fullPath) };
+}

package/src/lib/json-input.ts

@@ -0,0 +1,21 @@
+import { readFile } from "node:fs/promises";
+import { ZodType } from "zod";
+
+/**
+ * Reads, parses, and validates a JSON argument that names a file, or "-" to read
+ * from stdin (for use when the JSON is too large/awkward to pass as a file path,
+ * e.g. piped from another command). Requires a zod schema so untrusted JSON is
+ * never used until its shape is confirmed.
+ */
+export async function readJsonInput<T>(source: string, schema: ZodType<T>): Promise<T> {
+  const raw = source === "-" ? await readStdin() : await readFile(source, "utf-8");
+  return schema.parse(JSON.parse(raw));
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Array<Buffer> = [];
+  for await (const chunk of process.stdin){
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}

package/src/lib/lock-io.ts

@@ -0,0 +1,18 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ROSTERLOCK_V1_CASTER_JSONSCHEMA } from "@roster-lock/shared";
+import { RosterLockV1Config } from "@roster-lock/types";
+
+export function readLock(path: string): RosterLockV1Config {
+  const json = JSON.parse(readFileSync(resolve(process.cwd(), path), "utf-8"));
+  return ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(json, true);
+}
+
+export function writeLock(path: string, lock: RosterLockV1Config): void {
+  ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(lock, true);
+  writeFileSync(resolve(process.cwd(), path), JSON.stringify(lock, null, 2) + "\n");
+}
+
+export function defaultLockPath(title: string, version: string): string {
+  return resolve(process.cwd(), `${title}-${version}.rosterlock.json`);
+}

package/src/lib/parse.ts

@@ -0,0 +1,42 @@
+import { Count } from "@roster-lock/types";
+
+export function parseKeyValueList(value: string | undefined): Record<string, string> {
+  if(!value) return {};
+  const result: Record<string, string> = {};
+  for(const pair of value.split(",")){
+    const trimmed = pair.trim();
+    if(!trimmed) continue;
+    const eq = trimmed.indexOf("=");
+    if(eq === -1) throw new Error(`Invalid key=value pair: "${trimmed}"`);
+    result[trimmed.slice(0, eq)] = trimmed.slice(eq + 1);
+  }
+  return result;
+}
+
+export function parseCommaList(value: string | undefined): Array<string> {
+  if(!value) return [];
+  return value.split(",").map((v) => v.trim()).filter((v) => v.length > 0);
+}
+
+export function parseCount(value: string): Count {
+  if(value === "*") return "*";
+  if(value.includes(":")){
+    const [minRaw, maxRaw] = value.split(":");
+    const min = Number.parseInt(minRaw, 10);
+    if(Number.isNaN(min)) throw new Error(`Invalid count range: "${value}"`);
+    const max: number | "*" = maxRaw === "*" ? "*" : Number.parseInt(maxRaw, 10);
+    if(max !== "*" && Number.isNaN(max)) throw new Error(`Invalid count range: "${value}"`);
+    return [min, max];
+  }
+  const n = Number.parseInt(value, 10);
+  if(Number.isNaN(n)) throw new Error(`Invalid count: "${value}"`);
+  return n;
+}
+
+export function parseStrategy(value: string): "mandatory" | "personal" | "shared" | "on demand" {
+  const normalized = value === "on-demand" ? "on demand" : value;
+  if(!["mandatory", "personal", "shared", "on demand"].includes(normalized)){
+    throw new Error(`Invalid strategy: "${value}" (expected mandatory|personal|shared|on-demand)`);
+  }
+  return normalized as "mandatory" | "personal" | "shared" | "on demand";
+}

package/src/lib/piece-scan.ts

@@ -0,0 +1,19 @@
+import { getAssetsOfFiles, collectAssetFileErrors, calculatePieceVersion } from "@roster-lock/shared";
+import { RosterLockV1Config } from "@roster-lock/types";
+import { walkRelative, getFileFromRoot } from "./fs-walk";
+
+type PieceDefinition = RosterLockV1Config["engine"]["pieceDefinitions"][string];
+
+export async function scanPieceFolder(
+  folder: string,
+  pathVariables: Record<string, string>,
+  pieceDefinition: PieceDefinition,
+){
+  const assetInfo = await getAssetsOfFiles(walkRelative(folder), pathVariables, pieceDefinition);
+  const errors = collectAssetFileErrors(assetInfo);
+  const version = await calculatePieceVersion(
+    assetInfo.filesWithAssets,
+    (relativePath) => getFileFromRoot(folder, relativePath)
+  );
+  return { version, errors };
+}