@ssobig/writer-cli 0.2.0

package/tools/writer-cli/bin/ssobig-writer-daemon.cjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+"use strict";
+
+const { cliError, normalizeError, redact } = require("../src/errors.cjs");
+
+function loadDaemonApp() {
+  try { return require("../src/daemon-app.cjs"); }
+  catch (error) {
+    throw cliError("E_DAEMON_APP_UNAVAILABLE", "Writer daemon application을 불러올 수 없습니다.", null, error);
+  }
+}
+
+async function main(options = {}) {
+  if (String(options.platform || process.platform) === "win32") {
+    throw cliError("E_PLATFORM_UNSUPPORTED", "Windows에서는 background daemon을 지원하지 않습니다. ssobig-writer의 in-process backend를 사용해 주세요.");
+  }
+  const argv = options.argv || process.argv.slice(2);
+  if (argv.some(argument => argument !== "--foreground") || argv.filter(argument => argument === "--foreground").length > 1) {
+    throw cliError("E_USAGE", "ssobig-writer-daemon은 --foreground option만 지원합니다.");
+  }
+  const app = options.app || loadDaemonApp();
+  if (typeof app?.runDaemon !== "function") throw cliError("E_DAEMON_APP_UNAVAILABLE", "Writer daemon application에 runDaemon()이 없습니다.");
+  return app.runDaemon({ foreground: true, enforceUpdates: true, ...(process.env.SSOBIG_WRITER_AGENT_CACHE_DIR ? { cacheDir: process.env.SSOBIG_WRITER_AGENT_CACHE_DIR } : {}) });
+}
+
+if (require.main === module) {
+  main().catch(error => {
+    const normalized = normalizeError(error);
+    process.stderr.write(`${JSON.stringify({ ok: false, error: { code: normalized.code, message: redact(normalized.message) } })}\n`);
+    process.exitCode = normalized.code === "E_USAGE" ? 2 : 1;
+  });
+}
+
+module.exports = Object.freeze({ loadDaemonApp, main });

package/tools/writer-cli/bin/ssobig-writer.cjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+"use strict";
+
+const { runCli } = require("../src/commands.cjs");
+const { redact } = require("../src/errors.cjs");
+
+runCli(process.argv.slice(2), { enforceUpdates: true }).then(code => {
+  process.exitCode = code;
+}).catch(error => {
+  process.stderr.write(`${JSON.stringify({ ok: false, error: { code: "E_WRITER_CLI_FATAL", message: redact(error?.message || error) } })}\n`);
+  process.exitCode = 1;
+});

package/tools/writer-cli/package-lock.json

@@ -0,0 +1,121 @@
+{
+  "name": "@ssobig/writer-cli",
+  "version": "0.2.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@ssobig/writer-cli",
+      "version": "0.2.0",
+      "dependencies": {
+        "@supabase/supabase-js": "2.110.9"
+      },
+      "bin": {
+        "ssobig-writer": "bin/ssobig-writer.cjs",
+        "ssobig-writer-daemon": "bin/ssobig-writer-daemon.cjs"
+      },
+      "engines": {
+        "node": ">=22.13.0"
+      }
+    },
+    "node_modules/@supabase/auth-js": {
+      "version": "2.110.9",
+      "resolved": "https://registry.npmjs.org/@supabase/auth-js/-/auth-js-2.110.9.tgz",
+      "integrity": "sha512-XQIWyJfwEUdtzinuLUWPNSJbJKWdCQPqC7dDY45lA1qhX/OzvGPE+4OyPPZVOVWVh4DlPvk5RT2XL6SEAY0MoA==",
+      "license": "MIT",
+      "dependencies": {
+        "tslib": "2.8.1"
+      },
+      "engines": {
+        "node": ">=22.0.0"
+      }
+    },
+    "node_modules/@supabase/functions-js": {
+      "version": "2.110.9",
+      "resolved": "https://registry.npmjs.org/@supabase/functions-js/-/functions-js-2.110.9.tgz",
+      "integrity": "sha512-iSL6ih4vWK5Myc1lCuDoApfeB3Ov3cZIExvlCuQEZTzyzOKG4SLxVKPrBZG/QzwAjp7TEy0LCd0zZQtE5UAaDQ==",
+      "license": "MIT",
+      "dependencies": {
+        "tslib": "2.8.1"
+      },
+      "engines": {
+        "node": ">=22.0.0"
+      }
+    },
+    "node_modules/@supabase/phoenix": {
+      "version": "0.4.5",
+      "resolved": "https://registry.npmjs.org/@supabase/phoenix/-/phoenix-0.4.5.tgz",
+      "integrity": "sha512-aAn9H9ovVyeApKy11OWOrrOGq8DV68yWeH4ud2lN9fzn4aO8Zb5GLL9m1pUg9nLqIcT+ZDfAcsZe0E/nqdv2lw==",
+      "license": "MIT"
+    },
+    "node_modules/@supabase/postgrest-js": {
+      "version": "2.110.9",
+      "resolved": "https://registry.npmjs.org/@supabase/postgrest-js/-/postgrest-js-2.110.9.tgz",
+      "integrity": "sha512-YEfUzBMNkDE9OMfjzZnVgJH9h7y+wxxXryrgYk/t3boVtjPPlfwTdWRx8YkihuIbl4zxzdG4I0yiS4nd4Lmj8Q==",
+      "license": "MIT",
+      "dependencies": {
+        "tslib": "2.8.1"
+      },
+      "engines": {
+        "node": ">=22.0.0"
+      }
+    },
+    "node_modules/@supabase/realtime-js": {
+      "version": "2.110.9",
+      "resolved": "https://registry.npmjs.org/@supabase/realtime-js/-/realtime-js-2.110.9.tgz",
+      "integrity": "sha512-XHau+5jIOEAtS9hNiSrL4/2SXSt0EApChsj+f2VJL2mL+eicpUYLkANBu+5awFLIjXGOkys+ClYQ7Dg/3UTHcA==",
+      "license": "MIT",
+      "dependencies": {
+        "@supabase/phoenix": "0.4.5",
+        "tslib": "2.8.1"
+      },
+      "engines": {
+        "node": ">=22.0.0"
+      }
+    },
+    "node_modules/@supabase/storage-js": {
+      "version": "2.110.9",
+      "resolved": "https://registry.npmjs.org/@supabase/storage-js/-/storage-js-2.110.9.tgz",
+      "integrity": "sha512-UmyL+SB4cOBsejAaJ8LnLIm31585shJtnTezCCLMHyo2AauoH13sKJqPllf/8HMcGYqd0a4kHrA5t2nz+MSARA==",
+      "license": "MIT",
+      "dependencies": {
+        "iceberg-js": "^0.8.1",
+        "tslib": "2.8.1"
+      },
+      "engines": {
+        "node": ">=22.0.0"
+      }
+    },
+    "node_modules/@supabase/supabase-js": {
+      "version": "2.110.9",
+      "resolved": "https://registry.npmjs.org/@supabase/supabase-js/-/supabase-js-2.110.9.tgz",
+      "integrity": "sha512-C8UVe+x6hymwiLdJntQCm9zMD5+40tWF6j+17Z6g8NJnBAWEiuM9wXYAqgDzGAQF6oqrkHddmnZwWZZtEp0zeA==",
+      "license": "MIT",
+      "dependencies": {
+        "@supabase/auth-js": "2.110.9",
+        "@supabase/functions-js": "2.110.9",
+        "@supabase/postgrest-js": "2.110.9",
+        "@supabase/realtime-js": "2.110.9",
+        "@supabase/storage-js": "2.110.9"
+      },
+      "engines": {
+        "node": ">=22.0.0"
+      }
+    },
+    "node_modules/iceberg-js": {
+      "version": "0.8.1",
+      "resolved": "https://registry.npmjs.org/iceberg-js/-/iceberg-js-0.8.1.tgz",
+      "integrity": "sha512-1dhVQZXhcHje7798IVM+xoo/1ZdVfzOMIc8/rgVSijRK38EDqOJoGula9N/8ZI5RD8QTxNQtK/Gozpr+qUqRRA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/tslib": {
+      "version": "2.8.1",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
+      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
+      "license": "0BSD"
+    }
+  }
+}

package/tools/writer-cli/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@ssobig/writer-cli",
+  "version": "0.2.0",
+  "private": true,
+  "description": "Internal agent-safe CLI for SSOBIG WRITER manuscript and asset operations",
+  "type": "commonjs",
+  "bin": {
+    "ssobig-writer": "bin/ssobig-writer.cjs",
+    "ssobig-writer-daemon": "bin/ssobig-writer-daemon.cjs"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build:public": "node scripts/build-public-package.cjs",
+    "verify:public": "node scripts/verify-public-package.cjs",
+    "test": "node --test ../../tests/writer-cli-*.test.cjs"
+  },
+  "dependencies": {
+    "@supabase/supabase-js": "2.110.9"
+  }
+}

package/tools/writer-cli/skills/ssobig-writer-cli/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: ssobig-writer-cli
+description: Safely discover and use the public SSOBIG WRITER CLI for manuscript, Component, asset, checkpoint, and project operations.
+---
+
+# SSOBIG WRITER CLI
+
+Use this skill when a task asks you to inspect or change a Writer project through `ssobig-writer`. Treat the CLI, not this document, as the source of truth for command syntax. Start with the narrowest discovery call that answers the question:
+
+```bash
+ssobig-writer <group> --help
+ssobig-writer <group> <command> --help
+ssobig-writer command-schema <group.command> --compact
+```
+
+Do not dump the complete schema when one group or leaf is enough. The root schema intentionally returns only group summaries; a group returns leaf summaries; an exact leaf returns full inputs, examples, and safety metadata.
+
+Route by intent and read only the relevant reference:
+
+- Installation, sign-in, diagnostics, updates, or project-local skill setup: `references/install-auth.md`
+- Finding manuscript values or reading targeted Component data: `references/read-search.md`
+- Project identity, versions, Component reads, and reviewed data plans: `references/projects-components.md`
+- Asset pointers, checkpoint history, restore plans, and receipts: `references/assets-checkpoints.md`
+- Any failure, conflict, authorization issue, or boundary response: `references/errors.md`
+
+The authoritative manuscript source is Writer Component data. Never bypass the CLI with raw SQL, generic database updates, a Supabase management client, or a service-role credential. Never place manuscript values in source code, View HTML/JavaScript, local caches, or ad-hoc JSON as a substitute for Component data.
+
+For every production mutation, follow this sequence without shortcuts:
+
+1. Read the authoritative current state.
+2. Create a plan with the dedicated `plan-*` command.
+3. Present a human-readable review of the exact target and changes.
+4. Run `apply` only after the user explicitly authorizes that mutation.
+5. Read the authoritative state again and retain the receipt privately.
+
+A general request to inspect code or explain behavior does not authorize manuscript mutation. Plan and receipt files can contain confidential content; store them in a private ignored directory and never commit them.
+
+`E_CODE_CHANGE_REQUIRED` is a hard stop. It means the requested operation changes shared schemas, Component composition, Renderer/View behavior, identity, or another boundary outside the content CLI. Do not work around it. Report the boundary and separate the request into a reviewed code or migration task.

package/tools/writer-cli/skills/ssobig-writer-cli/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SSOBIG Writer CLI"
+  short_description: "Discover and use Writer CLI safely"
+  default_prompt: "Use $ssobig-writer-cli to discover the narrowest safe Writer CLI command for this task."

package/tools/writer-cli/skills/ssobig-writer-cli/references/assets-checkpoints.md

@@ -0,0 +1,5 @@
+# Assets and checkpoints
+
+Asset pointers are owned by the dedicated asset Component. Use only `asset plan-upload` or `asset plan-delete`; do not patch pointers through generic Component data. Validate the selected project, asset ID, file type, and expected prior entry before review and apply.
+
+Checkpoint commands provide history, snapshots, diffs, creation plans, and restore plans. A restore is a production mutation and follows plan, review, explicit authorization, apply, authoritative read-back. Keep plan and receipt files private. Use `checkpoint diff` to make the review understandable before a restore.

package/tools/writer-cli/skills/ssobig-writer-cli/references/errors.md

@@ -0,0 +1,10 @@
+# Errors and boundaries
+
+- `E_CLI_UPDATE_REQUIRED`: install the indicated latest npm package, then retry. The original operation was not sent.
+- `E_CODE_CHANGE_REQUIRED`: hard boundary; do not use SQL or another client. Separate a code or migration task.
+- `E_CONFLICT`: authoritative data changed after the plan. Read again and create a new plan.
+- `E_AUTH_REQUIRED`, `E_AUTH_EXPIRED`, `E_AUTHORIZATION`: use the supported login flow or ask an authorized staff member; never handle tokens directly.
+- `E_SKILL_CONFLICT`: an unmanaged or user-modified skill file is present. Preserve it and inspect status/diff; do not overwrite it.
+- Validation and usage errors: inspect the exact leaf help/schema and correct the request. Do not coerce unknown templates, renderers, bindings, identities, or schemas.
+
+Registry-unavailable update warnings are sanitized and non-blocking unless the local cache already records a newer required version.

package/tools/writer-cli/skills/ssobig-writer-cli/references/install-auth.md

@@ -0,0 +1,7 @@
+# Install, authentication, and diagnostics
+
+Use targeted help for `version`, `doctor`, `auth`, and `skills`. Install the npm package explicitly; there is no `postinstall` workspace mutation. Run `ssobig-writer skills install --target <workspace>` to install the bundled skill in both supported agent directories, or select one platform with `--codex` or `--claude`.
+
+Check `version --check` before long work. From CLI 0.2.0 onward, outdated server-access commands stop with `E_CLI_UPDATE_REQUIRED`; local help, schemas, diagnostics, logout, daemon cleanup, and skill management remain available. Registry outages fail open unless a cached newer version is already known.
+
+Authentication uses the supported staff flow. Never request, print, persist, or transmit access tokens. Use `doctor` for sanitized installation, credential-store, network, update, and daemon-version diagnostics.

package/tools/writer-cli/skills/ssobig-writer-cli/references/projects-components.md

@@ -0,0 +1,7 @@
+# Projects and Components
+
+Project commands expose identity, versions, and reviewed project-level plans. Component commands are the supported path for authoritative manuscript values. Read first, preserve the selected project/version/Instance identity, and use a dedicated `plan-*` command for changes.
+
+Generic Component patching changes only an existing Instance's `data`. It cannot change Component composition, metadata, View bindings, templates, schemas, project identity, or storage paths. If the CLI returns `E_CODE_CHANGE_REQUIRED`, stop and report that a separate code or migration review is required.
+
+Never apply a generated plan until the user has reviewed a human-readable summary and explicitly authorized the production mutation. Read back the same Component after apply.

package/tools/writer-cli/skills/ssobig-writer-cli/references/read-search.md

@@ -0,0 +1,5 @@
+# Read and search
+
+Start with `search` when the target location is unknown, then use the returned stable identifier with `read`, `component get`, or `agent get`. Prefer exact project, Component, path, and value filters. Use `--fresh` when authoritative refresh is desirable and `--require-fresh` when stale indexed data is unacceptable.
+
+Avoid broad corpus dumps. Inspect exact syntax through `search --help`, `read --help`, or the exact leaf schema. Search and read output may contain confidential manuscript content; summarize only what the task needs.

package/tools/writer-cli/src/agent-paths.cjs

@@ -0,0 +1,114 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const config = require("../../../config.js");
+const { cliError } = require("./errors.cjs");
+
+function projectRef() {
+  try { return new URL(config.supabaseUrl).hostname.split(".")[0]; }
+  catch (error) { throw cliError("E_CONFIGURATION", "Supabase project ref를 확인할 수 없습니다.", null, error); }
+}
+
+function localAppData(options = {}) {
+  const environment = options.environment || process.env;
+  const homeDirectory = options.homeDirectory || os.homedir();
+  return environment.LOCALAPPDATA || path.join(homeDirectory, "AppData", "Local");
+}
+
+function defaultAgentCacheDir(options = {}) {
+  const platform = String(options.platform || process.platform);
+  if (platform === "win32") return path.join(localAppData(options), "SSOBIG", "WriterCLI", "cache", "v1", projectRef());
+  return path.join(options.homeDirectory || os.homedir(), "Library", "Caches", "com.ssobig.writer-agent", "v1", projectRef());
+}
+
+function defaultDaemonDirectory(options = {}) {
+  const platform = String(options.platform || process.platform);
+  if (platform === "win32") return path.join(localAppData(options), "SSOBIG", "WriterCLI", "daemon", projectRef());
+  return path.join(options.homeDirectory || os.homedir(), "Library", "Caches", "ssobig-wa", projectRef());
+}
+
+function resolveAgentPaths(options = {}) {
+  const platform = String(options.platform || process.platform);
+  const defaults = { platform, environment: options.environment, homeDirectory: options.homeDirectory };
+  const cacheDir = path.resolve(String(options.cacheDir || defaultAgentCacheDir(defaults)));
+  const daemonDir = path.resolve(String(options.daemonDir || (options.cacheDir ? cacheDir : defaultDaemonDirectory(defaults))));
+  const identity = String(options.userId || "");
+  const userKey = identity ? crypto.createHash("sha256").update(identity).digest("hex").slice(0, 32) : "";
+  return Object.freeze({
+    cacheDir,
+    daemonDir,
+    socketPath: platform === "win32" ? null : path.join(daemonDir, "d.sock"),
+    pidPath: path.join(daemonDir, "daemon.pid"),
+    ...(userKey ? {
+      userCacheDir: path.join(cacheDir, "users", userKey),
+      indexPath: path.join(cacheDir, "users", userKey, "manuscript-index.sqlite3")
+    } : {})
+  });
+}
+
+function ensurePrivateDirectory(directory, fsApi = fs, options = {}) {
+  const platform = String(options.platform || process.platform);
+  try {
+    if (fsApi.lstatSync(directory).isSymbolicLink()) throw cliError("E_CACHE_PERMISSIONS", `Writer agent cache는 symbolic link일 수 없습니다: ${directory}`);
+  } catch (error) { if (error.code !== "ENOENT") throw error; }
+  fsApi.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const initial = fsApi.lstatSync(directory);
+  if (initial.isSymbolicLink() || !initial.isDirectory()) throw cliError("E_CACHE_PERMISSIONS", `Writer agent cache는 symbolic link가 아닌 directory여야 합니다: ${directory}`);
+  if (platform === "win32") return directory;
+  if (typeof process.getuid === "function" && initial.uid !== process.getuid()) {
+    throw cliError("E_CACHE_PERMISSIONS", `Writer agent cache의 소유자가 현재 사용자와 다릅니다: ${directory}`);
+  }
+  try { fsApi.chmodSync(directory, 0o700); }
+  catch (error) { throw cliError("E_CACHE_PERMISSIONS", `Writer agent cache 권한을 설정할 수 없습니다: ${directory}`, null, error); }
+  const stat = fsApi.statSync(directory);
+  if (!stat.isDirectory() || (stat.mode & 0o077) !== 0) {
+    throw cliError("E_CACHE_PERMISSIONS", `Writer agent cache는 현재 사용자만 접근할 수 있어야 합니다: ${directory}`);
+  }
+  return directory;
+}
+
+function purgeAllAgentIndexes(options = {}) {
+  const fsApi = options.fs || fs;
+  const platform = String(options.platform || process.platform);
+  const cacheDir = resolveAgentPaths({
+    cacheDir: options.cacheDir,
+    platform,
+    environment: options.environment,
+    homeDirectory: options.homeDirectory
+  }).cacheDir;
+  const usersDir = path.join(cacheDir, "users");
+  let userEntries;
+  try {
+    const usersStat = fsApi.lstatSync(usersDir);
+    if (usersStat.isSymbolicLink() || !usersStat.isDirectory()
+      || (platform !== "win32" && typeof process.getuid === "function" && usersStat.uid !== process.getuid())) {
+      throw cliError("E_CACHE_PERMISSIONS", "Writer agent users cache가 안전한 private directory가 아닙니다.");
+    }
+    userEntries = fsApi.readdirSync(usersDir, { withFileTypes: true });
+  }
+  catch (error) { if (error.code === "ENOENT") return { purged: true, removedFiles: 0 }; throw error; }
+  const allowedFiles = new Set([
+    "manuscript-index.sqlite3", "manuscript-index.sqlite3-journal", "manuscript-index.sqlite3-wal", "manuscript-index.sqlite3-shm",
+    "manuscript-index.json", "index.sqlite3", "index.sqlite3-journal", "index.sqlite3-wal", "index.sqlite3-shm", "index.json"
+  ]);
+  let removedFiles = 0;
+  for (const entry of userEntries) {
+    if (!/^[a-f0-9]{32}$/.test(entry.name) || !entry.isDirectory() || entry.isSymbolicLink()) continue;
+    const userDir = path.join(usersDir, entry.name);
+    const stat = fsApi.lstatSync(userDir);
+    if (platform !== "win32" && typeof process.getuid === "function" && stat.uid !== process.getuid()) continue;
+    for (const child of fsApi.readdirSync(userDir, { withFileTypes: true })) {
+      if (!allowedFiles.has(child.name) || !child.isFile() || child.isSymbolicLink()) continue;
+      fsApi.unlinkSync(path.join(userDir, child.name));
+      removedFiles += 1;
+    }
+    try { fsApi.rmdirSync(userDir); } catch (error) { if (!["ENOTEMPTY", "ENOENT"].includes(error.code)) throw error; }
+  }
+  try { fsApi.rmdirSync(usersDir); } catch (error) { if (!["ENOTEMPTY", "ENOENT"].includes(error.code)) throw error; }
+  return { purged: true, removedFiles };
+}
+
+module.exports = Object.freeze({ defaultAgentCacheDir, defaultDaemonDirectory, resolveAgentPaths, ensurePrivateDirectory, purgeAllAgentIndexes });