@takuhon/cli 0.8.2 → 0.9.0

package/dist/index.d.ts

@@ -3,9 +3,9 @@
  * `@takuhon/cli` entry point — the `takuhon` command.
  *
  * Exposes `--version` / `--help`, the local profile commands (`validate`,
- * `migrate`, `restore`, `export`, `import`, `build`, `dev`), and a pointer to
- * `create-takuhon` for scaffolding. The `sync` subcommand lands in a subsequent
- * release.
+ * `migrate`, `restore`, `export`, `import`, `build`, `dev`), `sync` (push a
+ * local profile to a deployment), and a pointer to `create-takuhon` for
+ * scaffolding.
  *
  * `main` is pure (returns an exit code, never calls `process.exit`); the only
  * place that exits the process is {@link run}, invoked either when this module

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync8, realpathSync } from "fs";
+import { readFileSync as readFileSync9, realpathSync } from "fs";
 import { stdin, stdout } from "process";
 import { createInterface } from "readline/promises";
 import { fileURLToPath } from "url";
@@ -1512,11 +1512,272 @@ function isNotFound2(error) {
   return typeof error === "object" && error !== null && error.code === "ENOENT";
 }
 
-// src/validate-command.ts
+// src/sync-command.ts
 import { readFileSync as readFileSync7 } from "fs";
 import { validate as validate6 } from "@takuhon/core";
 var DEFAULT_PATH7 = "takuhon.json";
-var USAGE7 = `Usage: takuhon validate [path]
+var ADMIN_PROFILE_PATH = "/api/admin/profile";
+var TOKEN_ENV = "TAKUHON_ADMIN_TOKEN";
+var USAGE7 = `Usage: takuhon sync [path] --url <base-url> [--if-match <etag>] [--dry-run]
+
+Push a local takuhon.json to a deployed takuhon instance by calling its admin
+write endpoint (PUT <base-url>/api/admin/profile). With no path, syncs
+./takuhon.json in the current working directory.
+
+The local file is the source of truth: by default the push is unconditional
+(a mirror). Pass --if-match <etag> to opt into optimistic locking (the server
+returns 409 if the stored version no longer matches). The document is sent
+as-is after a local schema check; run \`takuhon migrate\` first if it is an
+older schema version.
+
+The admin bearer token is read from the ${TOKEN_ENV} environment variable, e.g.:
+  ${TOKEN_ENV}=... takuhon sync --url https://me.example
+
+Options:
+  --url <base-url> Required. Absolute http(s) origin of the deployment.
+  --if-match <etag> Send If-Match for optimistic locking (opt-in).
+  --dry-run        Validate locally and report what would be sent; no request.
+
+Exit codes: 0 = synced (or dry-run ok), 1 = local invalid / remote refused
+(422 / 409), 2 = bad arguments / file missing / unreadable / not JSON / token
+unset / auth failure / network error / other non-success response.
+`;
+async function runSync(args = [], deps = {}) {
+  if (args[0] === "--help" || args[0] === "-h") {
+    return { code: 0, stdout: USAGE7, stderr: "" };
+  }
+  const parsed = parseArgs7(args);
+  if ("error" in parsed) {
+    return {
+      code: 2,
+      stdout: "",
+      stderr: `${parsed.error}
+Run \`takuhon sync --help\` for usage.
+`
+    };
+  }
+  return syncProfile(parsed, deps);
+}
+function parseArgs7(args) {
+  let path;
+  let url;
+  let ifMatch;
+  let dryRun = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--dry-run") {
+      dryRun = true;
+      continue;
+    }
+    if (arg === "--url" || arg === "--if-match") {
+      const value = args[i + 1];
+      if (value === void 0 || value === "" || value.startsWith("-")) {
+        return { error: `takuhon: \`${arg}\` requires a value.` };
+      }
+      if (arg === "--url") url = value;
+      else ifMatch = value;
+      i++;
+      continue;
+    }
+    if (arg.startsWith("--url=")) {
+      const value = arg.slice("--url=".length);
+      if (value === "") return { error: "takuhon: `--url` requires a value." };
+      url = value;
+      continue;
+    }
+    if (arg.startsWith("--if-match=")) {
+      const value = arg.slice("--if-match=".length);
+      if (value === "") return { error: "takuhon: `--if-match` requires a value." };
+      ifMatch = value;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      return { error: `takuhon: unknown option \`${arg}\` for \`sync\`.` };
+    }
+    if (path !== void 0) {
+      return { error: "takuhon: `sync` takes at most one path argument." };
+    }
+    path = arg;
+  }
+  if (url === void 0) {
+    return { error: "takuhon: `sync` requires `--url <base-url>`." };
+  }
+  const base = parseOrigin(url);
+  if ("error" in base) return base;
+  return { path: path ?? DEFAULT_PATH7, url: base.origin, ifMatch, dryRun };
+}
+function parseOrigin(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return { error: "takuhon: `--url` must be an absolute http(s) URL." };
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return { error: "takuhon: `--url` must be an absolute http(s) URL." };
+  }
+  if (parsed.username !== "" || parsed.password !== "" || parsed.search !== "" || parsed.hash !== "" || parsed.pathname !== "/" && parsed.pathname !== "") {
+    return {
+      error: "takuhon: `--url` must be the deployment's origin (e.g. https://me.example), with no path, query, or credentials."
+    };
+  }
+  return { origin: parsed.origin };
+}
+function redact(text, secret) {
+  return secret === "" ? text : text.split(secret).join("***");
+}
+function unquoteETag(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"') && trimmed.length >= 2) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+async function syncProfile(parsed, deps) {
+  const { path, url, ifMatch, dryRun } = parsed;
+  let raw;
+  try {
+    raw = readFileSync7(path, "utf8");
+  } catch {
+    return { code: 2, stdout: "", stderr: `takuhon: cannot read '${path}'.
+` };
+  }
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return { code: 2, stdout: "", stderr: `takuhon: '${path}' is not valid JSON: ${detail}
+` };
+  }
+  const result = validate6(data);
+  if (!result.ok) {
+    const lines = result.errors.map((e) => `  ${e.pointer || "/"}: ${e.message}`);
+    return {
+      code: 1,
+      stdout: "",
+      stderr: `takuhon: '${path}' is not a valid takuhon profile; refusing to sync:
+${lines.join("\n")}
+`
+    };
+  }
+  const endpoint = `${url}${ADMIN_PROFILE_PATH}`;
+  const body = `${JSON.stringify(result.data)}
+`;
+  const bytes = Buffer.byteLength(body, "utf8");
+  if (dryRun) {
+    const lock = ifMatch !== void 0 ? `, If-Match "${unquoteETag(ifMatch)}"` : "";
+    return {
+      code: 0,
+      stdout: `would sync ${path} -> ${endpoint} (${String(bytes)} bytes${lock})
+--dry-run: nothing sent.
+`,
+      stderr: ""
+    };
+  }
+  const getToken = deps.getToken ?? (() => process.env[TOKEN_ENV]);
+  const token = getToken();
+  if (token === void 0 || token === "") {
+    return {
+      code: 2,
+      stdout: "",
+      stderr: `takuhon: ${TOKEN_ENV} is not set; sync needs the deployment's admin token.
+Set it for this command only, e.g.:
+  ${TOKEN_ENV}=... takuhon sync --url ${url}
+`
+    };
+  }
+  const headers = {
+    "content-type": "application/json",
+    authorization: `Bearer ${token}`
+  };
+  if (ifMatch !== void 0) {
+    headers["if-match"] = `"${unquoteETag(ifMatch)}"`;
+  }
+  const fetchImpl = deps.fetch ?? fetch;
+  let res;
+  try {
+    res = await fetchImpl(endpoint, { method: "PUT", headers, body });
+  } catch (error) {
+    const detail = redact(error instanceof Error ? error.message : String(error), token);
+    return { code: 2, stdout: "", stderr: `takuhon: could not reach ${endpoint}: ${detail}
+` };
+  }
+  return interpretResponse(res, { path, url, endpoint });
+}
+async function interpretResponse(res, target) {
+  const { path, url, endpoint } = target;
+  if (res.ok) {
+    const version = await readVersion(res);
+    if (version === void 0) {
+      return {
+        code: 2,
+        stdout: "",
+        stderr: `takuhon: unexpected response from ${endpoint} (HTTP ${String(res.status)} but no meta.version); is --url a takuhon deployment?
+`
+      };
+    }
+    return { code: 0, stdout: `synced ${path} -> ${url} (version ${version})
+`, stderr: "" };
+  }
+  const problem = await readProblem(res);
+  const status = res.status;
+  if (status === 409) {
+    const current = problem?.currentVersion;
+    const hint = current !== void 0 ? `remote is at version ${current}. Re-sync against it, or drop --if-match to overwrite.` : "the stored version no longer matches --if-match. Re-sync, or drop --if-match to overwrite.";
+    return { code: 1, stdout: "", stderr: `takuhon: sync conflict (409): ${hint}
+` };
+  }
+  if (status === 422) {
+    const errors = Array.isArray(problem?.errors) ? problem.errors : [];
+    const lines = errors.map((e) => `  ${e.path}: ${e.message}`);
+    const detail2 = lines.length > 0 ? `:
+${lines.join("\n")}` : ".";
+    return {
+      code: 1,
+      stdout: "",
+      stderr: `takuhon: the deployment rejected the profile (422)${detail2}
+`
+    };
+  }
+  if (status === 401 || status === 403) {
+    const reason = status === 401 ? `unauthorized (401); check ${TOKEN_ENV}` : "forbidden (403); the request origin may not be allowed";
+    return { code: 2, stdout: "", stderr: `takuhon: ${reason}.
+` };
+  }
+  const detail = problem?.detail ?? res.statusText ?? "";
+  const tail = detail ? `: ${detail}` : ".";
+  return { code: 2, stdout: "", stderr: `takuhon: sync failed (${String(status)})${tail}
+` };
+}
+async function readVersion(res) {
+  try {
+    const parsed = await res.json();
+    const version = parsed.meta?.version;
+    return typeof version === "string" ? version : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function readProblem(res) {
+  let text;
+  try {
+    text = await res.text();
+  } catch {
+    return void 0;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+
+// src/validate-command.ts
+import { readFileSync as readFileSync8 } from "fs";
+import { validate as validate7 } from "@takuhon/core";
+var DEFAULT_PATH8 = "takuhon.json";
+var USAGE8 = `Usage: takuhon validate [path]
 
 Validate a takuhon.json against the takuhon schema. With no path, validates
 ./takuhon.json in the current working directory.
@@ -1525,7 +1786,7 @@ Exit codes: 0 = valid, 1 = invalid, 2 = file missing / unreadable / not JSON.
 `;
 function runValidate(args = []) {
   if (args[0] === "--help" || args[0] === "-h") {
-    return { code: 0, stdout: USAGE7, stderr: "" };
+    return { code: 0, stdout: USAGE8, stderr: "" };
   }
   if (args.length > 1) {
     return {
@@ -1537,10 +1798,10 @@ function runValidate(args = []) {
   return validateFile(args[0]);
 }
 function validateFile(pathArg) {
-  const target = pathArg ?? DEFAULT_PATH7;
+  const target = pathArg ?? DEFAULT_PATH8;
   let raw;
   try {
-    raw = readFileSync7(target, "utf8");
+    raw = readFileSync8(target, "utf8");
   } catch {
     return {
       code: 2,
@@ -1561,7 +1822,7 @@ function validateFile(pathArg) {
 `
     };
   }
-  const result = validate6(data);
+  const result = validate7(data);
   if (result.ok) {
     return {
       code: 0,
@@ -1582,7 +1843,7 @@ ${lines.join("\n")}
 }
 
 // src/index.ts
-var pkg = JSON.parse(readFileSync8(new URL("../package.json", import.meta.url), "utf8"));
+var pkg = JSON.parse(readFileSync9(new URL("../package.json", import.meta.url), "utf8"));
 var VERSION = pkg.version;
 var HELP = `takuhon ${VERSION}
 
@@ -1608,15 +1869,14 @@ Commands:
   takuhon dev [path] [--port <n>]      Serve a takuhon.json as a local static preview,
                                        re-rendered on each request (default port: 4321).
                                        --base-url <url> adds canonical/hreflang links.
+  takuhon sync [path] --url <url>      Push a takuhon.json to a deployment's admin API
+                                       (PUT <url>/api/admin/profile). Reads the admin token
+                                       from TAKUHON_ADMIN_TOKEN. --if-match <etag> opts into
+                                       optimistic locking; --dry-run previews without sending.
 
 Scaffolding a new profile project:
   npx create-takuhon my-profile
   npx create-takuhon my-profile --license CC-BY-4.0
-
-The sync subcommand is planned for a future release.
-Track progress at:
-
-  https://github.com/takuhon-dev/takuhon
 `;
 async function main(argv) {
   const first = argv[0];
@@ -1651,6 +1911,9 @@ async function main(argv) {
     const confirm = stdin.isTTY ? promptConfirm : void 0;
     return emit(await runRestore(argv.slice(1), { confirm }));
   }
+  if (first === "sync") {
+    return emit(await runSync(argv.slice(1)));
+  }
   process.stderr.write(
     `takuhon: unknown command '${first}'
 Run \`takuhon --help\` for usage. For scaffolding a new project, use \`create-takuhon\`.