@playgenx/components 0.2.0 → 0.2.1

package/bin/state-cli.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+/**
+ * playgenx-state — CLI for inspecting and operating on
+ * PlaygroundState snapshots.
+ *
+ * Pure ESM, no extra deps. Reads JSON from stdin (or argv),
+ * writes JSON to stdout.
+ *
+ * Subcommands:
+ *
+ *   snapshot    Pretty-print a snapshot in the v1 envelope format.
+ *               Accepts a JSON object on stdin (the snapshot you
+ *               captured from `state.snapshot()` or a DebugSurface).
+ *
+ *   validate    Validate one or more stateKey strings from stdin.
+ *               Reads a JSON array of strings, returns the per-key
+ *               verdict.
+ *
+ *   diff        Diff two snapshots. Reads `{prev, next}` from stdin
+ *               and returns the structured {added, changed, removed}
+ *               diff (or null when equal).
+ *
+ *   keys        List the sorted keys of a snapshot from stdin.
+ *
+ *   count       Count the keys in a snapshot from stdin.
+ *
+ * Usage examples (run from the components package root):
+ *
+ *   echo '{"volume": 5}' | node bin/state-cli.mjs snapshot
+ *   echo '["volume","user.name","bad key"]' | node bin/state-cli.mjs validate
+ *   echo '{"prev":{"a":1},"next":{"a":2,"b":3}}' | node bin/state-cli.mjs diff
+ *
+ * Exit codes:
+ *
+ *   0  success
+ *   1  bad subcommand
+ *   2  bad input (not parseable as JSON, wrong shape, etc.)
+ *   3  validation failure (one or more keys rejected)
+ *
+ * @packageDocumentation
+ */
+
+import {
+  dumpState,
+  diffSnapshots,
+  validateStateKey,
+} from '../dist/index.mjs';
+
+/**
+ * Read all of stdin into a string. Node-only.
+ */
+async function readStdin() {
+  if (process.stdin.isTTY) {
+    // Interactive / no pipe — return empty; the caller will treat
+    // this as "no input" and print usage.
+    return '';
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+function usage() {
+  return [
+    'Usage: playgenx-state <subcommand> [input]',
+    '',
+    'Subcommands:',
+    '  snapshot    Pretty-print a state snapshot (JSON on stdin)',
+    '  validate    Validate an array of stateKey strings (JSON array on stdin)',
+    '  diff        Diff two snapshots ({prev, next} on stdin)',
+    '  keys        List sorted keys of a snapshot (JSON on stdin)',
+    '  count       Count keys in a snapshot (JSON on stdin)',
+    '',
+    'Reads from stdin when no arg is given.',
+  ].join('\n');
+}
+
+function ok(payload) {
+  process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+}
+
+function fail(code, msg) {
+  process.stderr.write(`error: ${msg}\n`);
+  process.exit(code);
+}
+
+/**
+ * Convert an arbitrary snapshot to the StateEnvelope shape. The
+ * input is whatever the caller passed; we expect a plain object.
+ */
+function envelope(input) {
+  const keys = Object.keys(input).sort();
+  return { version: 1, keys, values: { ...input } };
+}
+
+async function main(argv) {
+  const sub = argv[0];
+  if (!sub || sub === '-h' || sub === '--help') {
+    process.stdout.write(usage() + '\n');
+    return 0;
+  }
+  const stdinPayload = (await readStdin()).trim();
+  const argPayload = argv[1];
+
+  switch (sub) {
+    case 'snapshot': {
+      const input = parseObject(argPayload ?? stdinPayload);
+      // Re-use the library's envelope so the CLI output matches the
+      // canonical dumpState shape. (We don't have a real store to
+      // pass to dumpState; envelope() builds the same structure.)
+      const env = envelope(input);
+      process.stdout.write(JSON.stringify(env, null, 2) + '\n');
+      // Reference dumpState so it's not tree-shaken — the import
+      // is documented as the canonical envelope producer.
+      void dumpState;
+      return 0;
+    }
+
+    case 'validate': {
+      const input = parseArray(argPayload ?? stdinPayload);
+      const results = input.map((k) => {
+        if (typeof k !== 'string') {
+          return { key: String(k), ok: false, error: 'must be a string' };
+        }
+        const err = validateStateKey(k);
+        return err === null
+          ? { key: k, ok: true }
+          : { key: k, ok: false, error: err };
+      });
+      const anyFailed = results.some((r) => !r.ok);
+      ok(results);
+      return anyFailed ? 3 : 0;
+    }
+
+    case 'diff': {
+      const input = parseObject(argPayload ?? stdinPayload);
+      if (!('prev' in input) || !('next' in input)) {
+        fail(2, 'diff expects {prev, next}');
+      }
+      const prev = input.prev;
+      const next = input.next;
+      if (typeof prev !== 'object' || prev === null) fail(2, 'prev must be an object');
+      if (typeof next !== 'object' || next === null) fail(2, 'next must be an object');
+      const d = diffSnapshots(prev, next);
+      ok(d);
+      return 0;
+    }
+
+    case 'keys': {
+      const input = parseObject(argPayload ?? stdinPayload);
+      ok(Object.keys(input).sort());
+      return 0;
+    }
+
+    case 'count': {
+      const input = parseObject(argPayload ?? stdinPayload);
+      ok({ keys: Object.keys(input).length });
+      return 0;
+    }
+
+    default:
+      process.stderr.write(usage() + '\n');
+      return 1;
+  }
+}
+
+function parseObject(raw) {
+  if (raw === '') fail(2, 'expected a JSON object on stdin or as argv[1]');
+  try {
+    const v = JSON.parse(raw);
+    if (typeof v !== 'object' || v === null || Array.isArray(v)) {
+      fail(2, 'expected a JSON object');
+    }
+    return v;
+  } catch (err) {
+    fail(2, `JSON parse error: ${err.message}`);
+  }
+}
+
+function parseArray(raw) {
+  if (raw === '') fail(2, 'expected a JSON array on stdin or as argv[1]');
+  try {
+    const v = JSON.parse(raw);
+    if (!Array.isArray(v)) fail(2, 'expected a JSON array');
+    return v;
+  } catch (err) {
+    fail(2, `JSON parse error: ${err.message}`);
+  }
+}
+
+main(process.argv.slice(2))
+  .then((code) => process.exit(code))
+  .catch((err) => fail(2, err.message ?? String(err)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playgenx/components",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Default React 19 implementations for every entry in DEFAULT_REGISTRY. Pair with @playgenx/registry and the parser/validator pipeline.",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -11,8 +11,12 @@
       "import": "./dist/index.mjs"
     }
   },
+  "bin": {
+    "playgenx-state": "./bin/state-cli.mjs"
+  },
   "files": [
-    "dist"
+    "dist",
+    "bin"
   ],
   "scripts": {
     "build": "tsdown",