@roster-lock/config-editor-cli 0.0.1

package/dist/lib/schemas.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectionOverridesSchemas = exports.pieceMetaOverridesSchema = exports.pieceOverridesSchema = exports.pieceDefinitionSchema = void 0;
+const zod_1 = require("zod");
+const countSchema = zod_1.z.union([
+    zod_1.z.number().int(),
+    zod_1.z.literal("*"),
+    zod_1.z.tuple([zod_1.z.number().int(), zod_1.z.union([zod_1.z.number().int(), zod_1.z.literal("*")])]),
+]);
+const assetSchema = zod_1.z.object({
+    name: zod_1.z.string(),
+    classification: zod_1.z.enum(["logic", "media", "doc"]),
+    count: countSchema,
+    glob: zod_1.z.array(zod_1.z.string()),
+}).strict();
+exports.pieceDefinitionSchema = zod_1.z.object({
+    selectionStrategy: zod_1.z.enum(["mandatory", "personal", "shared", "on demand"]),
+    requires: zod_1.z.array(zod_1.z.string()),
+    pathVariables: zod_1.z.array(zod_1.z.string()),
+    assets: zod_1.z.array(assetSchema),
+}).strict();
+const pieceHumanInfoSchema = zod_1.z.object({
+    name: zod_1.z.string(),
+    author: zod_1.z.string(),
+    url: zod_1.z.string(),
+    image: zod_1.z.string().optional(),
+}).strict();
+exports.pieceOverridesSchema = zod_1.z.object({
+    humanInfo: pieceHumanInfoSchema.optional(),
+    downloadSources: zod_1.z.array(zod_1.z.string()).optional(),
+    pathVariables: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional(),
+}).strict();
+const untrustedScriptRefSchema = zod_1.z.object({
+    src: zod_1.z.string(),
+    method: zod_1.z.string().optional(),
+}).strict();
+const jsonShallowValueSchema = zod_1.z.union([
+    zod_1.z.string(), zod_1.z.number(), zod_1.z.boolean(),
+    zod_1.z.array(zod_1.z.string()), zod_1.z.array(zod_1.z.number()), zod_1.z.array(zod_1.z.boolean()),
+]);
+const jsonShallowObjectSchema = zod_1.z.record(zod_1.z.string(), jsonShallowValueSchema);
+exports.pieceMetaOverridesSchema = zod_1.z.object({
+    schema: zod_1.z.record(zod_1.z.string(), zod_1.z.enum(["boolean", "number", "string", "boolean[]", "number[]", "string[]"])).optional(),
+    defaultMeta: jsonShallowObjectSchema.optional(),
+    values: zod_1.z.record(zod_1.z.string(), jsonShallowObjectSchema).optional(),
+}).strict();
+const selectedPieceSchema = zod_1.z.lazy(() => zod_1.z.object({
+    id: zod_1.z.string(),
+    required: zod_1.z.record(zod_1.z.string(), zod_1.z.object({
+        mandatory: zod_1.z.array(selectedPieceSchema),
+        selectable: zod_1.z.array(selectedPieceSchema),
+    }).strict()),
+}).strict());
+const userSelectionValidationSchema = zod_1.z.object({
+    count: countSchema,
+    unique: zod_1.z.boolean(),
+    banList: zod_1.z.array(zod_1.z.string()),
+    customValidation: zod_1.z.array(untrustedScriptRefSchema),
+}).strict();
+exports.selectionOverridesSchemas = {
+    normal: zod_1.z.object({
+        validation: userSelectionValidationSchema.optional(),
+        mergeAlgorithm: untrustedScriptRefSchema.optional(),
+    }).strict(),
+    preselected: zod_1.z.object({
+        pieces: zod_1.z.array(selectedPieceSchema).optional(),
+    }).strict(),
+    unselectable: zod_1.z.object({}).strict(),
+    "game-controlled": zod_1.z.object({}).strict(),
+};
+//# sourceMappingURL=schemas.js.map

package/dist/lib/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../src/lib/schemas.ts"],"names":[],"mappings":"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"}

package/dist/lib/semver-report.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printSemverReasons = printSemverReasons;
+function printSemverReasons(semver) {
+    const reasons = semver.getReasons();
+    for (const level of ["major", "minor", "patch"]) {
+        for (const { reason, info } of reasons[level]) {
+            console.log(`[${level}] ${reason} ${JSON.stringify(info)}`);
+        }
+    }
+    console.log(`Version: ${semver.toString()}`);
+}
+//# sourceMappingURL=semver-report.js.map

package/dist/lib/semver-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semver-report.js","sourceRoot":"","sources":["../../src/lib/semver-report.ts"],"names":[],"mappings":";;;AAEA,4BAAmC,MAAc;IAC/C,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;IACpC,KAAI,MAAM,KAAK,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAU,EAAC,CAAC;QACvD,KAAI,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,OAAO,CAAC,KAAK,CAAC,EAAC,CAAC;YAC5C,OAAO,CAAC,GAAG,CAAC,IAAI,KAAK,KAAK,MAAM,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,YAAY,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAC/C,CAAC"}

package/dist/lib/slugify.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.slugify = slugify;
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .trim()
+        .replace(/[\s_]+/g, '-')
+        .replace(/[^a-z0-9-]+/g, '')
+        .replace(/^-+|-+$/g, '')
+        .replace(/-+/g, '-');
+}
+//# sourceMappingURL=slugify.js.map

package/dist/lib/slugify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slugify.js","sourceRoot":"","sources":["../../src/lib/slugify.ts"],"names":[],"mappings":";;;AAAA,iBAAwB,IAAY;IAClC,OAAO,IAAI;SACR,WAAW,EAAE;SACb,IAAI,EAAE;SACN,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AACzB,CAAC"}

package/dist/version.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+exports.VERSION = "0.0.1";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":";;;AACa,QAAA,OAAO,GAAG,OAAO,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@roster-lock/config-editor-cli",
+  "version": "0.0.1",
+  "description": "A cli tool to build roster lock configs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/formula1/roster-lock.git",
+    "directory": "core/config-editor-cli"
+  },
+  "license": "JSON",
+  "author": "Sam Tobia",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "bin": {
+    "rosterlock-config-editor": "dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "commander": "^14.0.3",
+    "zod": "^4.4.3",
+    "@roster-lock/plugin-runtime": "0.1.0",
+    "@roster-lock/shared": "0.1.0",
+    "@roster-lock/types": "1.0.0",
+    "@roster-lock/utils": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.1",
+    "@yao-pkg/pkg": "^6.19.0",
+    "esbuild": "^0.28.1",
+    "rimraf": "^6.1.3",
+    "tsx": "^4.0.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.5"
+  },
+  "scripts": {
+    "prebuild": "node scripts/generate-version.js",
+    "build": "rimraf ./dist && tsc",
+    "predev": "node scripts/generate-version.js",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run tests/",
+    "prebundle": "pnpm run build",
+    "bundle": "node scripts/bundle.js",
+    "package": "pnpm run bundle && pkg pkg-build/bundle.cjs -t node24-linux-x64 -o bin/rosterlock-config-editor --no-signature"
+  }
+}

package/scripts/bundle.js

@@ -0,0 +1,15 @@
+// Bundles the compiled dist/index.js (and its workspace/node_modules deps) into a
+// single CJS file, so `pkg` can package it into a standalone binary without needing
+// to resolve pnpm's symlinked node_modules layout itself.
+const esbuild = require("esbuild");
+const { join } = require("node:path");
+
+esbuild.buildSync({
+  entryPoints: [join(__dirname, "..", "dist", "index.js")],
+  bundle: true,
+  platform: "node",
+  format: "cjs",
+  outfile: join(__dirname, "..", "pkg-build", "bundle.cjs"),
+});
+
+console.log("Bundled to pkg-build/bundle.cjs");

package/scripts/generate-version.js

@@ -0,0 +1,14 @@
+// Bakes package.json's version into a source file at build time, so the
+// version is embedded directly in the compiled/bundled output instead of
+// being read from package.json at runtime (which wouldn't be available if
+// this package is later packaged into a standalone binary, e.g. via pkg).
+const { writeFileSync, mkdirSync } = require("node:fs");
+const { join } = require("node:path");
+
+const pkg = require("../package.json");
+
+mkdirSync(join(__dirname, "..", "src"), { recursive: true });
+writeFileSync(
+  join(__dirname, "..", "src", "version.ts"),
+  `// Generated by scripts/generate-version.js — do not edit by hand.\nexport const VERSION = ${JSON.stringify(pkg.version)};\n`
+);

package/skills/rosterlock-config-editor/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: rosterlock-config-editor
+description: Create and edit roster-lock config drafts (engine piece types, roster pieces, selection config) using the rosterlock CLI, and validate/promote/publish them. Use whenever asked to build, edit, inspect, or validate a *.rosterlock.draft.json or *.rosterlock.json file.
+argument-hint: e.g. "create a draft for a new game called Foo" or "add a character piece type with a sprite asset"
+---
+
+# rosterlock CLI
+
+`rosterlock` is the CLI for building and editing roster-lock config files: the
+engine's piece-type definitions, the roster of actual pieces per type, and the
+per-type selection config. This skill ships inside the `@roster-lock/config-editor-cli`
+package itself (this file lives at `skills/rosterlock-config-editor/SKILL.md`
+relative to that package's root, `core/config-editor-cli/` in the roster-lock
+monorepo) so it travels with the CLI - installing or cloning just this package is
+enough to have it.
+
+It edits a **draft** file (`*.rosterlock.draft.json`), which wraps a `stagedLock`
+(the config being built), a `previousLock` (the last published baseline, for
+semver diffing), and draft-only bookkeeping (`draft.rosterPieceInfo`,
+`draft.selectionScriptInfo`).
+
+**`--help` is the source of truth for exact flags.** This doc gives you the shape
+of the CLI and the order operations need to happen in; run
+`$ROSTERLOCK <command> --help` before using a command you haven't used yet in this
+session, and re-check it if a command errors on unrecognized/missing flags - flags
+do change as the CLI evolves and this doc can drift.
+
+## Getting a runnable binary
+
+From this package's root, build a standalone binary (bundled via esbuild, packaged
+via `@yao-pkg/pkg` - runs without `pnpm`/`node_modules` on `PATH`):
+
+```bash
+pnpm run package
+```
+
+This produces `bin/rosterlock-config-editor` (gitignored, built on demand - targets
+`node24-linux-x64` by default; edit the `package` script in `package.json` to add
+other targets like `node24-macos-arm64`/`node24-win-x64` if needed). Check whether
+it already exists before rebuilding - it only needs to be regenerated after source
+changes:
+
+```bash
+test -x bin/rosterlock-config-editor || pnpm run package
+```
+
+If you only need to run something once and don't want to package a binary, and
+you're working inside the roster-lock monorepo (this package's dependencies are
+workspace-linked there), `pnpm dev -- <args>` runs the CLI directly from source
+via `tsx` (no build/package step, slightly slower startup).
+
+All examples below assume `ROSTERLOCK=./bin/rosterlock-config-editor` (adjust the
+path if you're invoking it from elsewhere - e.g. `pnpm dev --` if running from
+source).
+
+## Command map
+
+```
+$ROSTERLOCK draft init [path] --title <t> --author <a>
+$ROSTERLOCK draft from-lock <lockPath> [draftPath] [--clear-rosters]
+$ROSTERLOCK draft validate [-d <draft>]     # strict: every issue blocking publish/promote, at once
+$ROSTERLOCK draft promote [-d <draft>]      # stagedLock becomes the new previousLock baseline
+$ROSTERLOCK draft publish <outLockPath> [-d <draft>]  # writes a standalone versioned lock file
+
+$ROSTERLOCK validate [-d <draft>] [--lock <path>]  # looser structural check (drafts are allowed to be WIP)
+$ROSTERLOCK show [-d <draft>]                       # print stagedLock as JSON
+
+$ROSTERLOCK engine set-info --name <n> --engine-version <v> [-d <draft>]
+$ROSTERLOCK engine add-piece-type <pieceType> --strategy <s> [--requires <t,..>] [--path-variables <n,..>] [--json <file|->]
+$ROSTERLOCK engine edit-definition <pieceType> [--strategy <s>] [--requires <t,..>] [--path-variables <n,..>] [--json <file|->]
+$ROSTERLOCK engine add-asset <pieceType> <assetName> --classification <c> --count <n> --glob <pattern> [-d <draft>]
+$ROSTERLOCK engine remove-asset <pieceType> <assetName> [-d <draft>]
+$ROSTERLOCK engine remove-piece-type <pieceType> [-d <draft>]   # refuses if the roster still has pieces
+$ROSTERLOCK engine show [pieceType] [-d <draft>]
+
+$ROSTERLOCK roster add-piece <pieceType> <folder> [--path-variables <k=v,..>] [--download-source <url>] [--json <file|->]
+$ROSTERLOCK roster edit-piece <pieceType> <pieceId> [--name/--author/--url/--image <v>] [--add-download-source <url>] [--remove-download-source <url>] [--path-variables <k=v,..>] [--remove-path-variable <name>] [--json <file|->]
+$ROSTERLOCK roster rescan <pieceType> <pieceId> [folder] [--path-variables <k=v,..>]  # recompute hashes in place after asset/file changes; keeps id, humanInfo, downloadSources, requiredPieces
+$ROSTERLOCK roster test-download <pieceType> <pieceId> <sourceUrl>   # downloads and verifies a source's hash matches
+$ROSTERLOCK roster remove-piece <pieceType> <pieceId>
+$ROSTERLOCK roster list [pieceType] [-d <draft>]
+
+$ROSTERLOCK selection add-script <fileOrFolder> [--key <relPath>]
+$ROSTERLOCK selection set <pieceType> --type <normal|preselected|unselectable|game-controlled> [--json <file|->]
+$ROSTERLOCK selection run-script <scriptRef>
+$ROSTERLOCK selection show [-d <draft>]
+```
+
+The `-d, --draft <path>` option (present on almost every command) defaults to the
+sole `*.rosterlock.draft.json` file in the current directory - only pass it
+explicitly when there's more than one draft in play, or you're not running from
+the draft's directory.
+
+## Typical workflow
+
+1. **Start a draft.** Either `draft init` (empty) or `draft from-lock <existing.rosterlock.json>`
+   (start from a published lock; add `--clear-rosters` to keep the engine config
+   but start with empty rosters/selection - useful for "same game, new content
+   season").
+2. **Define the engine** (piece types): `engine add-piece-type`, then
+   `engine add-asset` for each asset the piece type needs. `engine edit-definition`
+   changes strategy/requires/path-variables later without re-adding assets.
+3. **Populate rosters** (actual pieces): `roster add-piece <type> <folder>` scans a
+   folder against the piece type's asset definitions and computes content hashes.
+   It needs at least one download source, from `--download-source`, a
+   `rosterlock.piece-meta.json` in the folder, or `--json`. Use `roster edit-piece`
+   to fix up humanInfo/sources/path-variables afterward. Its id is derived from
+   `humanInfo` (`@author/name`, or `#logicHash/mediaHash` if unnamed) - there's no
+   flag to set it directly. To update an **existing** piece's files (e.g. after
+   adding a new asset type or editing media) without changing its id or losing its
+   `requiredPieces`, use `roster rescan <type> <pieceId> [folder]` instead of
+   removing and re-adding it - `add-piece` always resets `requiredPieces` to empty
+   stubs, which `roster edit-piece` cannot restore.
+4. **Configure selection** per piece type: `selection set <type> --type <kind>`.
+   `normal` needs `validation` (count/unique/banList/customValidation); `preselected`
+   needs `pieces`; `unselectable`/`game-controlled` need neither - just `pieceMeta`
+   if you're using per-piece metadata. Pass the type-specific fields via `--json`
+   (see shape in `selection set --help`).
+5. **Validate before finishing up**: `draft validate` runs the full (non-draft)
+   schema against `stagedLock` and reports *every* issue in one pass (not just the
+   first) - use it to iterate through problems instead of running `publish`
+   repeatedly. (Plain `validate` without `draft` only checks structure - it
+   deliberately allows an in-progress/incomplete draft.)
+6. **Promote and/or publish**: `draft promote` moves `stagedLock` forward as the
+   new `previousLock` baseline (for future diffs) without producing an output file.
+   `draft publish <path>` writes a standalone, semver-bumped lock file and prints
+   why the version changed, without touching the draft.
+
+## `--json` inputs
+
+Several commands accept `--json <file>` to supply structured input too large/awkward
+for flags (full piece-type definitions, type-specific selection fields, bulk piece
+edits). Pass `-` instead of a file path to pipe JSON via stdin instead of writing a
+temp file - handy when generating the JSON programmatically:
+
+```bash
+echo '{"selectionStrategy":"shared","requires":[],"pathVariables":[],"assets":[]}' \
+  | $ROSTERLOCK engine edit-definition character --json -
+```
+
+Every `--json` input is validated with zod before use; the command's `--help`
+prints the exact expected shape (e.g. `Shape: { selectionStrategy: "mandatory" |
+... }`). A shape mismatch fails fast with a per-field error - fix the JSON and
+retry rather than guessing.
+
+## Error output
+
+Validation errors (from `--json` shape checks, or from `draft validate`/`publish`/
+`promote` against the full lock schema) print one issue per line as
+`<path> <message>`, and the process exits non-zero. Multiple issues are reported
+together, not just the first - read the whole list before making changes.

package/src/commands/draft/from-lock.ts

@@ -0,0 +1,34 @@
+import { Command } from "commander";
+import { resolve } from "node:path";
+import { EMPTY_ROSTER_DRAFT } from "@roster-lock/shared";
+import { cloneJSON } from "@roster-lock/utils";
+import { readLock } from "../../lib/lock-io";
+import { defaultDraftPath, writeDraft } from "../../lib/draft-io";
+import { withErrorHandling } from "../../lib/errors";
+
+export const fromLockCommand = new Command("from-lock")
+  .description("Create a new draft from an existing published lock file")
+  .argument("<lockPath>", "path to the published lock file")
+  .argument("[draftPath]", "where to write the draft (defaults to a name derived from the lock's title)")
+  .option(
+    "--clear-rosters",
+    "keep the lock's engine config, but start with empty rosters and no per-piece-type selection config"
+  )
+  .action(withErrorHandling(async (lockPath: string, draftPath: string | undefined, opts: { clearRosters?: boolean }) => {
+    const lock = readLock(lockPath);
+
+    const draft = cloneJSON(EMPTY_ROSTER_DRAFT);
+    draft.previousLock = cloneJSON(lock);
+    draft.stagedLock = cloneJSON(lock);
+
+    if(opts.clearRosters){
+      for(const pieceType of Object.keys(draft.stagedLock.rosters)){
+        draft.stagedLock.rosters[pieceType] = [];
+      }
+      draft.stagedLock.selection.piece = {};
+    }
+
+    const path = draftPath ? resolve(process.cwd(), draftPath) : defaultDraftPath(lock.title);
+    writeDraft(path, draft);
+    console.log(`Created draft: ${path}${opts.clearRosters ? " (rosters cleared)" : ""}`);
+  }));

package/src/commands/draft/index.ts

@@ -0,0 +1,5 @@
+export * from "./init";
+export * from "./from-lock";
+export * from "./promote";
+export * from "./publish";
+export * from "./validate";

package/src/commands/draft/init.ts

@@ -0,0 +1,21 @@
+import { Command } from "commander";
+import { resolve } from "node:path";
+import { EMPTY_ROSTER_DRAFT } from "@roster-lock/shared";
+import { cloneJSON } from "@roster-lock/utils";
+import { defaultDraftPath, writeDraft } from "../../lib/draft-io";
+import { withErrorHandling } from "../../lib/errors";
+
+export const initCommand = new Command("init")
+  .description("Create a new empty roster-lock draft")
+  .argument("[draftPath]", "where to write the draft (defaults to a name derived from --title)")
+  .option("--title <title>", "title to seed the staged lock with")
+  .option("--author <author>", "author to seed the staged lock with")
+  .action(withErrorHandling(async (draftPath: string | undefined, opts: { title?: string, author?: string }) => {
+    const draft = cloneJSON(EMPTY_ROSTER_DRAFT);
+    if(opts.title) draft.stagedLock.title = opts.title;
+    if(opts.author) draft.stagedLock.author = opts.author;
+
+    const path = draftPath ? resolve(process.cwd(), draftPath) : defaultDraftPath(opts.title);
+    writeDraft(path, draft);
+    console.log(`Created draft: ${path}`);
+  }));

package/src/commands/draft/promote.ts

@@ -0,0 +1,24 @@
+import { Command } from "commander";
+import { ROSTERLOCK_V1_CASTER_JSONSCHEMA, diffLocks } 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 { printSemverReasons } from "../../lib/semver-report";
+
+export const promoteCommand = withDraftOption(new Command("promote"))
+  .description("Move the staged lock forward as the new baseline (previousLock) for future diffs")
+  .action(withErrorHandling(async (opts: { draft?: string }) => {
+    const draftPath = resolveDraftPath(opts.draft);
+    const draft = readDraft(draftPath);
+
+    const updatedDraft = cloneJSON(draft);
+    ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(updatedDraft.stagedLock);
+
+    const semver = diffLocks(updatedDraft.previousLock, updatedDraft.stagedLock);
+    updatedDraft.stagedLock.version = semver.toString();
+    updatedDraft.previousLock = cloneJSON(updatedDraft.stagedLock);
+
+    writeDraft(draftPath, updatedDraft);
+    printSemverReasons(semver);
+  }));

package/src/commands/draft/publish.ts

@@ -0,0 +1,26 @@
+import { Command } from "commander";
+import { ROSTERLOCK_V1_CASTER_JSONSCHEMA, diffLocks } from "@roster-lock/shared";
+import { cloneJSON } from "@roster-lock/utils";
+import { resolveDraftPath, readDraft } from "../../lib/draft-io";
+import { writeLock } from "../../lib/lock-io";
+import { withDraftOption } from "../../lib/cli-options";
+import { withErrorHandling } from "../../lib/errors";
+import { printSemverReasons } from "../../lib/semver-report";
+
+export const publishCommand = withDraftOption(new Command("publish"))
+  .description("Publish the staged lock as a standalone, versioned lock file (does not modify the draft)")
+  .argument("<outLockPath>", "where to write the published lock file")
+  .action(withErrorHandling(async (outLockPath: string, opts: { draft?: string }) => {
+    const draftPath = resolveDraftPath(opts.draft);
+    const draft = readDraft(draftPath);
+
+    const stagedLock = cloneJSON(draft.stagedLock);
+    ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(stagedLock);
+
+    const semver = diffLocks(draft.previousLock, stagedLock);
+    stagedLock.version = semver.toString();
+
+    writeLock(outLockPath, stagedLock);
+    printSemverReasons(semver);
+    console.log(`Published: ${outLockPath}`);
+  }));

package/src/commands/draft/validate.ts

@@ -0,0 +1,30 @@
+import { Command } from "commander";
+import { ROSTERLOCK_V1_CASTER_JSONSCHEMA } from "@roster-lock/shared";
+import { resolveDraftPath, readDraft } from "../../lib/draft-io";
+import { withDraftOption } from "../../lib/cli-options";
+import { formatError } from "../../lib/errors";
+
+export const draftValidateCommand = withDraftOption(new Command("validate"))
+  .description(
+    "Report every issue blocking \"draft publish\"/\"draft promote\": runs the staged lock through the full " +
+    "(non-draft) schema and lists all failures at once, without writing anything"
+  )
+  .action(async (opts: { draft?: string }) => {
+    try {
+      const draftPath = resolveDraftPath(opts.draft);
+      const draft = readDraft(draftPath);
+
+      const result = ROSTERLOCK_V1_CASTER_JSONSCHEMA.safeCast(draft.stagedLock);
+      if(result.valid){
+        console.log("OK: staged lock is valid and ready to publish");
+        return;
+      }
+
+      console.error(`${result.error.length} issue(s) found in staged lock:`);
+      console.error(formatError(result.error));
+      process.exitCode = 1;
+    } catch(e){
+      console.error(formatError(e));
+      process.exitCode = 1;
+    }
+  });

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

@@ -0,0 +1,46 @@
+import { Command } from "commander";
+import { ROSTERLOCK_V1_CASTER_JSONSCHEMA, validatePieceDefinition } from "@roster-lock/shared";
+import { EngineAssetDefinition, AssetClassification } from "@roster-lock/types";
+import { resolveDraftPath, readDraft, writeDraft } from "../../lib/draft-io";
+import { withDraftOption } from "../../lib/cli-options";
+import { withErrorHandling } from "../../lib/errors";
+import { parseCount } from "../../lib/parse";
+
+function collectGlob(value: string, previous: Array<string>){
+  previous.push(value);
+  return previous;
+}
+
+export const addAssetCommand = withDraftOption(new Command("add-asset"))
+  .description("Add an asset definition to an existing piece type")
+  .argument("<pieceType>", "the piece type key")
+  .argument("<assetName>", "the asset's name")
+  .requiredOption("--classification <classification>", "logic|media|doc")
+  .requiredOption("--count <count>", "exact number, \"*\", or \"min:max\" (max may be \"*\")")
+  .option("--glob <pattern>", "glob pattern (repeatable)", collectGlob, [] as Array<string>)
+  .action(withErrorHandling(async (pieceType: string, assetName: string, opts: {
+    draft?: string, classification: string, count: string, glob: Array<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}"`);
+    if(opts.glob.length === 0) throw new Error("At least one --glob is required");
+    if(!["logic", "media", "doc"].includes(opts.classification)){
+      throw new Error(`Invalid --classification "${opts.classification}" (expected logic|media|doc)`);
+    }
+
+    const asset: EngineAssetDefinition = {
+      name: assetName,
+      classification: opts.classification as AssetClassification,
+      count: parseCount(opts.count),
+      glob: opts.glob,
+    };
+    definition.assets.push(asset);
+    validatePieceDefinition(pieceType, definition, draft.stagedLock.engine);
+    ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(draft.stagedLock);
+
+    writeDraft(draftPath, draft);
+    console.log(`Added asset "${assetName}" to piece type "${pieceType}"`);
+  }));

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

@@ -0,0 +1,56 @@
+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 addPieceTypeCommand = withDraftOption(new Command("add-piece-type"))
+  .description("Define a new piece type in the staged lock's engine")
+  .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")
+  .option("--path-variables <names>", "comma-separated list of path variable names")
+  .option(
+    "--json <file>",
+    "read 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);
+
+    if(draft.stagedLock.engine.pieceDefinitions[pieceType]){
+      throw new Error(`Piece type "${pieceType}" already exists; use "engine remove-piece-type" first`);
+    }
+
+    const definition: PieceDefinition = opts.json
+      ? await readJsonInput(opts.json, pieceDefinitionSchema)
+      : {
+        selectionStrategy: parseStrategy(requireOption(opts.strategy, "--strategy")),
+        requires: parseCommaList(opts.requires),
+        pathVariables: parseCommaList(opts.pathVariables),
+        assets: [],
+      };
+
+    draft.stagedLock.engine.pieceDefinitions[pieceType] = definition;
+    draft.stagedLock.rosters[pieceType] ??= [];
+    validatePieceDefinition(pieceType, definition, draft.stagedLock.engine);
+    ROSTERLOCK_V1_CASTER_JSONSCHEMA.cast(draft.stagedLock);
+
+    writeDraft(draftPath, draft);
+    console.log(`Added piece type: ${pieceType}`);
+  }));
+
+function requireOption(value: string | undefined, flag: string): string {
+  if(value === undefined) throw new Error(`${flag} is required unless --json is given`);
+  return value;
+}