@ssobig/writer-cli 0.2.0

package/tools/writer-cli/src/checkpoint-diff.cjs

@@ -0,0 +1,128 @@
+"use strict";
+
+const { equalJson } = require("./json.cjs");
+
+function escapePointerToken(value) {
+  return String(value).replaceAll("~", "~0").replaceAll("/", "~1");
+}
+
+function valueType(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+function appendChange(changes, operation, path, before, after, includeValues) {
+  const change = {
+    operation,
+    path: path || "",
+    beforeType: operation === "add" ? null : valueType(before),
+    afterType: operation === "remove" ? null : valueType(after)
+  };
+  if (includeValues) {
+    if (operation !== "add") change.before = structuredClone(before);
+    if (operation !== "remove") change.after = structuredClone(after);
+  }
+  changes.push(change);
+}
+
+function walkDiff(before, after, path, changes, includeValues) {
+  if (equalJson(before, after)) return;
+  if (Array.isArray(before) && Array.isArray(after)) {
+    const length = Math.max(before.length, after.length);
+    for (let index = 0; index < length; index += 1) {
+      const nextPath = `${path}/${index}`;
+      if (index >= before.length) appendChange(changes, "add", nextPath, undefined, after[index], includeValues);
+      else if (index >= after.length) appendChange(changes, "remove", nextPath, before[index], undefined, includeValues);
+      else walkDiff(before[index], after[index], nextPath, changes, includeValues);
+    }
+    return;
+  }
+  if (before && after && typeof before === "object" && typeof after === "object"
+    && !Array.isArray(before) && !Array.isArray(after)) {
+    const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])].sort();
+    for (const key of keys) {
+      const nextPath = `${path}/${escapePointerToken(key)}`;
+      if (!Object.hasOwn(before, key)) appendChange(changes, "add", nextPath, undefined, after[key], includeValues);
+      else if (!Object.hasOwn(after, key)) appendChange(changes, "remove", nextPath, before[key], undefined, includeValues);
+      else walkDiff(before[key], after[key], nextPath, changes, includeValues);
+    }
+    return;
+  }
+  appendChange(changes, "replace", path, before, after, includeValues);
+}
+
+function entrySummary(entry, includeData = false) {
+  const value = {
+    instanceId: String(entry.instance_id),
+    templateId: String(entry.template_id),
+    tabLabel: String(entry.tab_label || ""),
+    sortOrder: Number(entry.sort_order),
+    enabled: entry.is_enabled === true,
+    archived: entry.is_archived === true,
+    sourceRevision: Number(entry.source_revision ?? entry.revision),
+    dataHash: String(entry.data_hash || ""),
+    changedFromParent: entry.changed_from_parent === true
+  };
+  if (includeData) value.data = structuredClone(entry.data);
+  return value;
+}
+
+function snapshotSummary(snapshot, includeData = false) {
+  return {
+    checkpoint: snapshot.checkpoint,
+    components: snapshot.entries.map(entry => entrySummary(entry, includeData))
+  };
+}
+
+function diffSnapshots(before, after, options = {}) {
+  const includeValues = options.includeValues === true;
+  const beforeById = new Map(before.entries.map(entry => [String(entry.instance_id), entry]));
+  const afterById = new Map(after.entries.map(entry => [String(entry.instance_id), entry]));
+  const ids = [...new Set([...beforeById.keys(), ...afterById.keys()])].sort((left, right) => {
+    const leftOrder = Number(beforeById.get(left)?.sort_order ?? afterById.get(left)?.sort_order ?? 0);
+    const rightOrder = Number(beforeById.get(right)?.sort_order ?? afterById.get(right)?.sort_order ?? 0);
+    return leftOrder - rightOrder || left.localeCompare(right);
+  });
+  const components = [];
+  for (const instanceId of ids) {
+    const beforeEntry = beforeById.get(instanceId);
+    const afterEntry = afterById.get(instanceId);
+    if (!beforeEntry || !afterEntry) {
+      components.push({
+        instanceId,
+        templateId: String((afterEntry || beforeEntry).template_id),
+        change: beforeEntry ? "removed" : "added",
+        pathCount: 1,
+        paths: [{ operation: beforeEntry ? "remove" : "add", path: "" }]
+      });
+      continue;
+    }
+    const paths = [];
+    walkDiff(beforeEntry.data, afterEntry.data, "", paths, includeValues);
+    const metadataChanged = [
+      "template_id", "tab_label", "sort_order",
+      "is_enabled", "is_archived", "is_required", "is_removable", "editor_view_id",
+      "preview_view_id", "capabilities", "config"
+    ].some(key => !equalJson(beforeEntry[key], afterEntry[key]));
+    if (paths.length || metadataChanged) {
+      components.push({
+        instanceId,
+        templateId: String(afterEntry.template_id),
+        change: metadataChanged && !paths.length ? "metadata" : "modified",
+        metadataChanged,
+        pathCount: paths.length,
+        paths
+      });
+    }
+  }
+  return {
+    from: before.checkpoint,
+    to: after.checkpoint,
+    changedComponentCount: components.length,
+    changedPathCount: components.reduce((sum, item) => sum + item.pathCount, 0),
+    components
+  };
+}
+
+module.exports = Object.freeze({ entrySummary, snapshotSummary, diffSnapshots });

package/tools/writer-cli/src/command-registry.cjs

@@ -0,0 +1,152 @@
+"use strict";
+
+const { cliError } = require("./errors.cjs");
+
+const GLOBAL_INPUTS = Object.freeze([
+  Object.freeze({ name: "json", type: "boolean", required: false, description: "JSON output (default)." }),
+  Object.freeze({ name: "compact", type: "boolean", required: false, description: "Write compact JSON." }),
+  Object.freeze({ name: "help", type: "boolean", required: false, description: "Show scoped help." })
+]);
+
+const option = (name, value, description, extra = {}) => Object.freeze({ name, type: extra.type || "string", required: extra.required === true, value, description, ...extra });
+const positional = (name, description, extra = {}) => Object.freeze({ name, type: "positional", required: extra.required !== false, description, ...extra });
+
+const SERVER = Object.freeze({ serverAccess: true, updatePolicy: "required" });
+const LOCAL = Object.freeze({ serverAccess: false, updatePolicy: "allowed-outdated" });
+const READ = Object.freeze({ productionMutation: false, requiresReviewedPlan: false, requiresExplicitAuthorization: false, boundaryError: null });
+const PLAN = Object.freeze({ productionMutation: false, requiresReviewedPlan: false, requiresExplicitAuthorization: false, boundaryError: "E_CODE_CHANGE_REQUIRED" });
+const MUTATE = Object.freeze({ productionMutation: true, requiresReviewedPlan: true, requiresExplicitAuthorization: true, boundaryError: "E_CODE_CHANGE_REQUIRED" });
+
+function command(path, summary, inputs = [], examples = [], metadata = {}) {
+  const parts = path.split(".");
+  return Object.freeze({
+    path,
+    group: parts.length === 1 ? path : parts[0],
+    command: parts.join(" "),
+    summary,
+    inputs: Object.freeze(inputs),
+    examples: Object.freeze(examples),
+    ...READ,
+    ...LOCAL,
+    ...metadata
+  });
+}
+
+const project = option("project", "<slug|uuid>", "Writer project slug or UUID.", { required: true });
+const version = option("version", "<internal-n>", "Internal workspace version number.");
+const out = option("out", "<plan-file>", "Private output plan path.", { required: true });
+const message = option("message", "<checkpoint-message>", "Checkpoint message.");
+
+const COMMANDS = Object.freeze([
+  command("version", "Show installed CLI version and integrity.", [option("check", null, "Check npm latest.", { type: "boolean" })], ["ssobig-writer version --check"]),
+  command("doctor", "Run read-only installation and connectivity diagnostics.", [], ["ssobig-writer doctor"]),
+  command("command-schema", "Discover groups, leaves, or exact machine-readable command metadata.", [positional("scope", "Optional group or group.command scope.", { required: false })], ["ssobig-writer command-schema component.get --compact"]),
+  command("auth.login", "Sign in through the staff authentication flow.", [option("no-open", null, "Print the login URL without opening a browser.", { type: "boolean" })], ["ssobig-writer auth login --no-open"], SERVER),
+  command("auth.whoami", "Show the current authenticated staff identity.", [], ["ssobig-writer auth whoami"], SERVER),
+  command("auth.logout", "Clear local credentials and cached agent state.", [], ["ssobig-writer auth logout"]),
+  command("agent.start", "Start the private local Writer daemon.", [], ["ssobig-writer agent start"], SERVER),
+  command("agent.status", "Show local daemon status.", [], ["ssobig-writer agent status"]),
+  command("agent.stop", "Stop the local daemon.", [], ["ssobig-writer agent stop"]),
+  command("agent.get", "Read one indexed match by identifier.", [option("match", "<match-id>", "Search match identifier.", { required: true }), option("max-characters", "<100-20000>", "Maximum returned characters.")], ["ssobig-writer agent get --match <match-id>"], SERVER),
+  command("agent.apply", "Apply an agent-produced reviewed plan.", [option("plan", "<plan-file>", "Reviewed plan path.", { required: true }), option("receipt", "<receipt-file>", "Receipt output path.", { required: true })], ["ssobig-writer agent apply --plan plan.json --receipt receipt.json"], { ...SERVER, ...MUTATE }),
+  command("agent.purge", "Purge local manuscript indexes.", [], ["ssobig-writer agent purge"]),
+  command("sync", "Refresh the local manuscript index.", [], ["ssobig-writer sync"], SERVER),
+  command("read", "Read indexed or authoritative Component data.", [option("project", "<slug|uuid>", "Limit to a project."), version, option("component", "<id|template-id>", "Limit to a Component."), option("pointer", "<json-pointer>", "Read a JSON pointer."), option("include-assets", null, "Include asset metadata.", { type: "boolean" }), option("fresh", null, "Prefer an authoritative refresh.", { type: "boolean" }), option("require-fresh", null, "Fail unless authoritative data is available.", { type: "boolean" })], ["ssobig-writer read --project <slug> --component <template-id> --fresh"], SERVER),
+  command("search", "Search Component values and paths.", [option("query", "<text>", "Text query."), option("value-json", "<json-scalar>", "Typed exact value."), option("mode", "<all|exact|substring|regex>", "Search mode."), option("project", "<slug|uuid>", "Limit to a project."), version, option("component", "<id|template-id>", "Limit to a Component."), option("path", "<json-pointer>", "Exact JSON pointer."), option("path-prefix", "<json-pointer>", "JSON pointer prefix."), option("path-glob", "<glob>", "JSON pointer glob."), option("field", "<field>", "Field selector."), option("value-type", "<type>", "Value type."), option("limit", "<n>", "Maximum matches."), option("flags", "<regex-flags>", "Regular-expression flags."), option("case-sensitive", null, "Use case-sensitive matching.", { type: "boolean" }), option("include-assets", null, "Include asset metadata.", { type: "boolean" }), option("fresh", null, "Prefer an authoritative refresh.", { type: "boolean" }), option("require-fresh", null, "Fail unless authoritative data is available.", { type: "boolean" })], ["ssobig-writer search --query <text> --project <slug>", "ssobig-writer search --mode all --path-prefix /characters"], SERVER),
+  command("project.list", "List visible Writer projects.", [option("status", "<active|archived>", "Project status.")], ["ssobig-writer project list --status active"], SERVER),
+  command("project.show", "Show project identity and versions.", [project, option("status", "<active|archived>", "Project status.")], ["ssobig-writer project show --project <slug>"], SERVER),
+  command("project.plan-create", "Create a reviewed project creation plan.", [option("slug", "<slug>", "New project slug.", { required: true }), option("title", "<title>", "Project title.", { required: true }), out], ["ssobig-writer project plan-create --slug new-case --title 'New Case' --out plan.json"], { ...SERVER, ...PLAN }),
+  command("project.plan-import", "Create a reviewed import plan from a supported case export.", [option("source-root", "<case-directory>", "Source case root.", { required: true }), option("source-json", "<room-export.json>", "Source room export.", { required: true }), option("slug", "<slug>", "New project slug.", { required: true }), option("title", "<title>", "Project title.", { required: true }), out], ["ssobig-writer project plan-import --source-root case --source-json room.json --slug new-case --title 'New Case' --out plan.json"], { ...SERVER, ...PLAN }),
+  command("project.plan-archive", "Create a reviewed project archive plan.", [project, out], ["ssobig-writer project plan-archive --project <slug> --out plan.json"], { ...SERVER, ...PLAN }),
+  command("project.plan-restore", "Create a reviewed project restore plan.", [project, out], ["ssobig-writer project plan-restore --project <slug> --out plan.json"], { ...SERVER, ...PLAN }),
+  command("project.plan-set-catalog-demo", "Create a reviewed catalog-demo status plan.", [project, option("enabled", "<true|false>", "Catalog demo state.", { required: true }), out], ["ssobig-writer project plan-set-catalog-demo --project <slug> --enabled true --out plan.json"], { ...SERVER, ...PLAN }),
+  command("component.list", "List Components in a workspace.", [project, version], ["ssobig-writer component list --project <slug>"], SERVER),
+  command("component.get", "Read one authoritative Component Instance.", [project, version, option("instance", "<id|template-id>", "Component Instance or Template identifier.", { required: true })], ["ssobig-writer component get --project <slug> --instance <template-id>"], SERVER),
+  command("component.plan-patch", "Create a reviewed Component data patch plan.", [project, version, option("instance", "<id|template-id>", "Component Instance or Template identifier.", { required: true }), option("patch", "<file>", "JSON patch document.", { required: true }), out, message], ["ssobig-writer component plan-patch --project <slug> --instance <id> --patch patch.json --out plan.json"], { ...SERVER, ...PLAN }),
+  command("component.plan-layout-investigation-board", "Create a deterministic investigation-board layout plan.", [project, version, option("instance", "<id|template-id>", "Investigation board Component."), option("spec", "<layout-spec.json>", "Validated layout spec.", { required: true }), out, message], ["ssobig-writer component plan-layout-investigation-board --project <slug> --spec layout.json --out plan.json"], { ...SERVER, ...PLAN }),
+  command("component.plan-replace", "Create a reviewed indexed text replacement plan.", [option("match", "<match-id>", "Search match identifier.", { required: true }), option("old", "<text>", "Expected old text.", { required: true }), option("new", "<text>", "Replacement text.", { required: true }), out, option("occurrence", "<zero-based-index>", "Occurrence index."), message], ["ssobig-writer component plan-replace --match <id> --old old --new new --out plan.json"], { ...SERVER, ...PLAN }),
+  command("asset.list", "List immutable asset pointers.", [project, version], ["ssobig-writer asset list --project <slug>"], SERVER),
+  command("asset.plan-upload", "Create a reviewed asset upload plan.", [project, version, option("asset-id", "<id>", "Asset identifier.", { required: true }), option("file", "<path>", "JPEG, PNG, WebP, GIF, or JSON file.", { required: true }), out, message], ["ssobig-writer asset plan-upload --project <slug> --asset-id cover --file cover.webp --out plan.json"], { ...SERVER, ...PLAN }),
+  command("asset.plan-delete", "Create a reviewed asset delete plan.", [project, version, option("asset-id", "<id>", "Asset identifier.", { required: true }), out, message], ["ssobig-writer asset plan-delete --project <slug> --asset-id cover --out plan.json"], { ...SERVER, ...PLAN }),
+  command("checkpoint.list", "List workspace checkpoints.", [project, version, option("before", "<checkpoint-number>", "Pagination cursor."), option("limit", "<1-100>", "Maximum rows.")], ["ssobig-writer checkpoint list --project <slug> --limit 20"], SERVER),
+  command("checkpoint.status", "Show the current checkpoint head.", [project, version], ["ssobig-writer checkpoint status --project <slug>"], SERVER),
+  command("checkpoint.show", "Show one checkpoint snapshot.", [project, version, option("checkpoint", "<id|number>", "Checkpoint selector.", { required: true }), option("include-data", null, "Include manuscript data.", { type: "boolean" })], ["ssobig-writer checkpoint show --project <slug> --checkpoint 3"], SERVER),
+  command("checkpoint.diff", "Diff two checkpoints or Latest.", [project, version, option("from", "<id|number|latest>", "Diff base.", { required: true }), option("to", "<id|number|latest>", "Diff target.", { required: true }), option("include-values", null, "Include changed values.", { type: "boolean" })], ["ssobig-writer checkpoint diff --project <slug> --from 2 --to latest"], SERVER),
+  command("checkpoint.plan-create", "Create a reviewed checkpoint creation plan.", [project, version, option("message", "<message>", "Checkpoint message.", { required: true }), out], ["ssobig-writer checkpoint plan-create --project <slug> --message review --out plan.json"], { ...SERVER, ...PLAN }),
+  command("checkpoint.plan-restore", "Create a reviewed checkpoint restore plan.", [project, version, option("checkpoint", "<id|number>", "Checkpoint selector.", { required: true }), option("message", "<message>", "Checkpoint message.", { required: true }), out], ["ssobig-writer checkpoint plan-restore --project <slug> --checkpoint 3 --message restore --out plan.json"], { ...SERVER, ...PLAN }),
+  command("validate", "Validate the authoritative Component composition.", [project, version], ["ssobig-writer validate --project <slug>"], SERVER),
+  command("apply", "Apply one reviewed plan and optionally write a receipt.", [positional("plan-file", "Reviewed plan file."), option("receipt", "<receipt-file>", "Private receipt output path.")], ["ssobig-writer apply plan.json --receipt receipt.json"], { ...SERVER, ...MUTATE }),
+  command("skills.install", "Install the bundled project-local agent skill.", [option("target", "<workspace>", "Workspace root.", { required: true }), option("codex", null, "Install only to .agents/skills.", { type: "boolean" }), option("claude", null, "Install only to .claude/skills.", { type: "boolean" }), option("dry-run", null, "Report without changing files.", { type: "boolean" })], ["ssobig-writer skills install --target . --dry-run"]),
+  command("skills.status", "Inspect bundled skill installation state.", [option("target", "<workspace>", "Workspace root.", { required: true })], ["ssobig-writer skills status --target ."]),
+  command("skills.update", "Safely update managed skill files.", [option("target", "<workspace>", "Workspace root.", { required: true }), option("codex", null, "Update only .agents/skills.", { type: "boolean" }), option("claude", null, "Update only .claude/skills.", { type: "boolean" }), option("dry-run", null, "Report without changing files.", { type: "boolean" })], ["ssobig-writer skills update --target . --dry-run"]),
+  command("skills.remove", "Remove only manifest-owned skill files.", [option("target", "<workspace>", "Workspace root.", { required: true }), option("managed-only", null, "Required managed-file safety acknowledgement.", { type: "boolean", required: true }), option("codex", null, "Remove only from .agents/skills.", { type: "boolean" }), option("claude", null, "Remove only from .claude/skills.", { type: "boolean" }), option("dry-run", null, "Report without changing files.", { type: "boolean" })], ["ssobig-writer skills remove --target . --managed-only --dry-run"])
+]);
+
+const BY_PATH = new Map(COMMANDS.map(item => [item.path, item]));
+if (BY_PATH.size !== COMMANDS.length) throw new Error("Writer CLI command registry contains duplicate paths.");
+
+const GROUP_DESCRIPTIONS = Object.freeze({
+  version: "installation version", doctor: "installation diagnostics", "command-schema": "targeted machine metadata", auth: "staff authentication", agent: "local agent backend",
+  sync: "local index refresh", read: "targeted manuscript read", search: "targeted manuscript search", project: "project identity and plans",
+  component: "Component data and plans", asset: "asset pointers and plans", checkpoint: "workspace history", validate: "composition validation",
+  apply: "reviewed plan mutation", skills: "project-local agent skills"
+});
+
+function normalizeScope(value) {
+  if (Array.isArray(value)) return value.filter(Boolean).join(".");
+  return String(value || "").trim().replace(/\s+/g, ".");
+}
+
+function getCommand(value) { return BY_PATH.get(normalizeScope(value)) || null; }
+function groups() { return [...new Set(COMMANDS.map(item => item.group))]; }
+function groupCommands(group) { return COMMANDS.filter(item => item.group === group); }
+function allowedOptions(value) {
+  const item = getCommand(value);
+  if (!item) throw cliError("E_USAGE", `지원하지 않는 Writer CLI 명령입니다: ${normalizeScope(value)}`);
+  return new Set([...item.inputs.filter(input => input.type !== "positional").map(input => input.name), ...GLOBAL_INPUTS.map(input => input.name)]);
+}
+function booleanOptions() {
+  return new Set([...GLOBAL_INPUTS, ...COMMANDS.flatMap(item => item.inputs)].filter(input => input.type === "boolean").map(input => input.name));
+}
+
+function publicMetadata(item, full = true) {
+  const base = { path: item.path, command: item.command, summary: item.summary };
+  if (!full) return base;
+  return { ...base, inputs: item.inputs, examples: item.examples, serverAccess: item.serverAccess, productionMutation: item.productionMutation, requiresReviewedPlan: item.requiresReviewedPlan, requiresExplicitAuthorization: item.requiresExplicitAuthorization, updatePolicy: item.updatePolicy, boundaryError: item.boundaryError };
+}
+
+function commandSchema(scope = "") {
+  const normalized = normalizeScope(scope);
+  if (!normalized) return { kind: "groups", groups: groups().map(group => ({ group, summary: GROUP_DESCRIPTIONS[group], commandCount: groupCommands(group).length })) };
+  const exact = getCommand(normalized);
+  if (exact) return { kind: "command", command: publicMetadata(exact, true) };
+  const children = groupCommands(normalized);
+  if (children.length) return { kind: "group", group: normalized, commands: children.map(item => publicMetadata(item, false)) };
+  throw cliError("E_USAGE", `알 수 없는 command-schema scope입니다: ${normalized}`);
+}
+
+function rootHelp() {
+  const rows = groups().map(group => `  ${group.padEnd(11)} ${GROUP_DESCRIPTIONS[group]}`);
+  return `SSOBIG WRITER CLI\n\nUsage:\n  ssobig-writer <group|command> [options]\n  ssobig-writer <group> --help\n  ssobig-writer help <group> [command]\n  ssobig-writer command-schema [group|group.command] [--compact]\n\nCommands:\n${rows.join("\n")}\n\nEvery command writes one JSON document. Mutations require a reviewed plan.\nUse targeted help or command-schema to discover exact inputs.`;
+}
+
+function groupHelp(group) {
+  const children = groupCommands(group);
+  if (!children.length) throw cliError("E_USAGE", `알 수 없는 help group입니다: ${group}`);
+  return `SSOBIG WRITER ${group}\n\nUsage:\n  ssobig-writer ${group} <command> [options]\n\nCommands:\n${children.map(item => `  ${item.command.padEnd(42)} ${item.summary}`).join("\n")}\n\nUse ssobig-writer ${group} <command> --help for exact inputs.`;
+}
+
+function leafHelp(item) {
+  const syntax = item.inputs.map(input => input.type === "positional" ? `<${input.name}>` : `${input.required ? "" : "["}--${input.name}${input.type === "boolean" ? "" : ` ${input.value || `<${input.name}>`}`}${input.required ? "" : "]"}`).join(" ");
+  const inputs = item.inputs.length ? `\n\nInputs:\n${item.inputs.map(input => `  ${input.type === "positional" ? `<${input.name}>` : `--${input.name}`.padEnd(22)} ${input.required ? "required; " : ""}${input.description}`).join("\n")}` : "";
+  return `SSOBIG WRITER ${item.command}\n\n${item.summary}\n\nUsage:\n  ssobig-writer ${item.command}${syntax ? ` ${syntax}` : ""}${inputs}\n\nExamples:\n${item.examples.map(example => `  ${example}`).join("\n")}`;
+}
+
+function helpFor(scope = "") {
+  const normalized = normalizeScope(scope);
+  if (!normalized) return rootHelp();
+  const exact = getCommand(normalized);
+  return exact ? leafHelp(exact) : groupHelp(normalized);
+}
+
+module.exports = Object.freeze({ COMMANDS, GLOBAL_INPUTS, getCommand, groups, groupCommands, allowedOptions, booleanOptions, commandSchema, helpFor, normalizeScope });