@publisle/cli 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@publisle/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Optional Node-only validation and explicit source upgrades.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./run": {
+      "types": "./dist/run.d.ts",
+      "import": "./dist/run.js",
+      "default": "./dist/run.js"
+    }
+  },
+  "bin": {
+    "publisle": "./dist/bin.js"
+  },
+  "dependencies": {
+    "@publisle/contracts": "0.1.0",
+    "@publisle/blocks-core": "0.1.0",
+    "@publisle/core": "0.1.0",
+    "@publisle/markdown": "0.1.0",
+    "@publisle/schema": "0.1.0"
+  },
+  "devDependencies": {
+    "@publisle/cli-research": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "NOTICE.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VoidReg/publisle.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/VoidReg/publisle#readme",
+  "types": "./dist/index.d.ts"
 }

package/src/bin.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { runCli } from "./run.ts";
+
+process.exitCode = await runCli(process.argv.slice(2), {
+  stdout: (text) => {
+    process.stdout.write(text);
+  },
+  stderr: (text) => {
+    process.stderr.write(text);
+  },
+});

package/src/index.ts

@@ -0,0 +1,279 @@
+import { coreBlockDefinitions } from "@publisle/blocks-core";
+import { lockDocument, type ContractBundle } from "@publisle/contracts";
+import { createRegistry, prepare, type PrepareOptions } from "@publisle/core";
+import {
+  fromMarkdown,
+  toMarkdown,
+  type MarkdownBlockCodec,
+} from "@publisle/markdown";
+import {
+  canonicalizeJson,
+  locateDiagnostic,
+  parseDocument,
+  parseJson,
+  JsonBoundaryError,
+  SchemaParseError,
+  type Diagnostic,
+  type Document,
+  type DocumentSourceMap,
+} from "@publisle/schema";
+
+export interface CliConfig {
+  readonly contractBundle?: ContractBundle;
+  /** Trusted host configuration, not reader-side code. Core blocks are the default registry. */
+  readonly prepare?: PrepareOptions;
+  readonly markdown?: { readonly codecs?: readonly MarkdownBlockCodec[] };
+  /**
+   * Research template registries are read by the optional @publisle/cli-research
+   * plugin; this Core config type stays free of Research imports.
+   */
+  readonly templates?: unknown;
+}
+
+export interface SourceOperation {
+  readonly command: "validate" | "upgrade";
+  readonly format: "json" | "markdown";
+  readonly sourceName: string;
+  readonly config?: CliConfig;
+}
+
+export interface SourceResult {
+  readonly diagnostics: readonly Diagnostic[];
+  /** Present only for a successful upgrade. This API never writes files. */
+  readonly output?: string;
+}
+
+function stable(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stable).join(",")}]`;
+  if (typeof value === "object" && value !== null)
+    return `{${Object.entries(value)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([key, entry]) => `${JSON.stringify(key)}:${stable(entry)}`)
+      .join(",")}}`;
+  return value === undefined ? "undefined" : JSON.stringify(value);
+}
+
+function semantics(document: Document): unknown {
+  return {
+    schemaVersion: document.schemaVersion,
+    metadata: document.metadata,
+    blocks: document.blocks.map(({ type, schemaVersion, data }) => ({
+      type,
+      schemaVersion,
+      data,
+    })),
+  };
+}
+
+/** Pure orchestration of the public import/parse/prepare/export boundaries. */
+export function processSource(
+  source: string,
+  options: SourceOperation,
+): SourceResult {
+  const diagnostics: Diagnostic[] = [];
+  let sourceMap: DocumentSourceMap | undefined;
+  const location = { source: options.sourceName, line: 1, column: 1 };
+  const error = (code: string, message: string): SourceResult => ({
+    diagnostics: [
+      ...diagnostics,
+      { level: "error", code, message, sourceLocation: location },
+    ],
+  });
+  const config = options.config ?? {};
+  const preparation: PrepareOptions = {
+    registry: createRegistry(coreBlockDefinitions),
+    unknownBlocks: options.command === "validate" ? "error" : "preserve",
+    ...config.prepare,
+  };
+  const markdownOptions = {
+    ...config.markdown,
+    sourceName: options.sourceName,
+    resolveSchemaVersion: (type: `${string}:${string}`) =>
+      preparation.registry.get(type)?.schemaVersion,
+  };
+  try {
+    let input: Document;
+    if (options.format === "markdown") {
+      const imported = fromMarkdown(source, markdownOptions);
+      diagnostics.push(...imported.diagnostics);
+      if (!imported.document) return { diagnostics };
+      input = imported.document;
+      sourceMap = imported.sourceMap;
+    } else {
+      const raw: unknown = parseJson(source);
+      input = parseDocument(raw);
+      // Parsing intentionally models only portable fields. An upgrade must not
+      // silently discard unmodeled author data at the envelope/block boundary.
+      if (options.command === "upgrade" && stable(raw) !== stable(input))
+        return error(
+          "unmodeled-source-fields",
+          "JSON contains fields outside the portable schema; move them into metadata.extensions or a block payload before upgrading.",
+        );
+    }
+    const originalPayloads = new Map(
+      input.blocks.map((block) => [
+        block.id,
+        {
+          schemaVersion: block.schemaVersion,
+          data: stable(block.data),
+        },
+      ]),
+    );
+    const prepared = prepare(input, {
+      ...preparation,
+      ...(sourceMap ? { sourceMap } : {}),
+    });
+    diagnostics.push(
+      ...prepared.diagnostics.map((item) =>
+        locateDiagnostic(item, sourceMap ?? { document: location, blocks: {} }),
+      ),
+    );
+    if (
+      !prepared.document ||
+      diagnostics.some(({ level }) => level === "error")
+    )
+      return { diagnostics };
+    if (options.command === "validate") return { diagnostics };
+
+    // Explicitly remove preparation flags/plans and serialize only the public wire envelope.
+    const upgraded = parseDocument({
+      ...(input.dependencies === undefined
+        ? {}
+        : { dependencies: input.dependencies }),
+      ...(input.extensions === undefined
+        ? {}
+        : { extensions: input.extensions }),
+      schemaVersion: prepared.document.schemaVersion,
+      ...(prepared.document.metadata === undefined
+        ? {}
+        : { metadata: prepared.document.metadata }),
+      blocks: prepared.document.blocks.map(
+        ({ id, type, schemaVersion, data, readable }) => ({
+          ...(readable === undefined ? {} : { readable }),
+          id,
+          type,
+          schemaVersion,
+          data,
+        }),
+      ),
+    });
+    for (const block of upgraded.blocks) {
+      const original = originalPayloads.get(block.id);
+      if (
+        original?.schemaVersion === block.schemaVersion &&
+        original.data !== stable(block.data)
+      )
+        diagnostics.push(
+          locateDiagnostic(
+            {
+              level: "warning",
+              code: "block-data-normalized",
+              message:
+                "Registered parsing/defaults/normalization changed this payload without a version change. Review the upgrade preview before writing.",
+              blockId: block.id,
+            },
+            sourceMap ?? { document: location, blocks: {} },
+          ),
+        );
+    }
+    if (options.format === "json")
+      return { diagnostics, output: `${JSON.stringify(upgraded, null, 2)}\n` };
+    const exported = toMarkdown(upgraded, {
+      ...config.markdown,
+      policy: "fallback",
+    });
+    diagnostics.push(
+      ...exported.diagnostics.map((item) => locateDiagnostic(item, sourceMap)),
+    );
+    if (
+      exported.markdown === undefined ||
+      diagnostics.some(({ level }) => level === "error")
+    )
+      return { diagnostics };
+    const roundTrip = fromMarkdown(exported.markdown, markdownOptions);
+    diagnostics.push(...roundTrip.diagnostics);
+    if (
+      !roundTrip.document ||
+      stable(semantics(roundTrip.document)) !== stable(semantics(upgraded))
+    )
+      return error(
+        "markdown-roundtrip-loss",
+        "Canonical Markdown cannot preserve this document's upgraded semantics. No output was produced; upgrade the JSON representation instead or fix the host codec.",
+      );
+    if (diagnostics.some(({ level }) => level === "error"))
+      return { diagnostics };
+    if (
+      upgraded.blocks.some(
+        (block, index) => block.id !== roundTrip.document?.blocks[index]?.id,
+      )
+    )
+      diagnostics.push({
+        level: "warning",
+        code: "markdown-block-ids-changed",
+        message:
+          "Canonical native Markdown regenerates some block IDs. Stable labels remain; use JSON when block identity must be retained.",
+        sourceLocation: location,
+      });
+    return { diagnostics, output: exported.markdown };
+  } catch (cause) {
+    return error(
+      cause instanceof SchemaParseError || cause instanceof JsonBoundaryError
+        ? cause.code
+        : "source-operation-failed",
+      cause instanceof Error ? cause.message : "Source processing failed.",
+    );
+  }
+}
+
+/** Explicit pinning preview/output; never mutates the original input or repins locked content. */
+export async function lockSource(
+  source: string,
+  options: Omit<SourceOperation, "command">,
+): Promise<SourceResult> {
+  try {
+    const imported =
+      options.format === "markdown"
+        ? fromMarkdown(source, {
+            ...options.config?.markdown,
+            sourceName: options.sourceName,
+          })
+        : undefined;
+    if (imported && !imported.document)
+      return { diagnostics: imported.diagnostics };
+    const raw = imported?.document ?? parseJson(source);
+    const document = parseDocument(raw);
+    if (canonicalizeJson(raw) !== canonicalizeJson(document))
+      throw new Error(
+        "Preserve original source: unsupported envelope fields must not be dropped while locking.",
+      );
+    const registry =
+      options.config?.prepare?.registry ?? createRegistry(coreBlockDefinitions);
+    const locked = await lockDocument(document, registry);
+    if (options.format === "json")
+      return {
+        output: JSON.stringify(locked.document, null, 2) + "\n",
+        diagnostics: imported?.diagnostics ?? [],
+      };
+    const exported = toMarkdown(locked.document, { policy: "archival" });
+    return {
+      ...(exported.markdown === undefined ? {} : { output: exported.markdown }),
+      diagnostics: [...(imported?.diagnostics ?? []), ...exported.diagnostics],
+    };
+  } catch (error) {
+    return {
+      diagnostics: [
+        {
+          level: "error",
+          code:
+            error instanceof Error &&
+            "code" in error &&
+            typeof error.code === "string"
+              ? error.code
+              : "document-lock-failed",
+          message: error instanceof Error ? error.message : "Locking failed.",
+          sourceLocation: { source: options.sourceName, line: 1, column: 1 },
+        },
+      ],
+    };
+  }
+}

package/src/run.ts

@@ -0,0 +1,355 @@
+import {
+  chmod,
+  lstat,
+  mkdtemp,
+  readFile,
+  rename,
+  rmdir,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
+import { dirname, extname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  isPlainObject,
+  parseDocument,
+  parseJson,
+  type Diagnostic,
+} from "@publisle/schema";
+import { toReadingMarkdown } from "@publisle/markdown";
+import { processSource, lockSource, type CliConfig } from "./index.ts";
+import {
+  exportSemanticDocument,
+  inspectDocument,
+  validateContractBundle,
+} from "@publisle/contracts";
+import { createRegistry } from "@publisle/core";
+import { coreBlockDefinitions } from "@publisle/blocks-core";
+
+/**
+ * The only sanctioned seam between the Core CLI and the Research profile: the
+ * optional plugin is loaded dynamically, so a Core-only install carries no
+ * research, template, or TeX tooling. Type-only knowledge of the plugin shape
+ * is erased at runtime.
+ */
+type ResearchPlugin = typeof import("@publisle/cli-research");
+
+const researchCommands = ["export", "bibliography", "doctor", "setup"] as const;
+
+type ResearchCommandName = (typeof researchCommands)[number];
+
+function isResearchCommand(
+  value: string | undefined,
+): value is ResearchCommandName {
+  return (researchCommands as readonly string[]).includes(value ?? "");
+}
+
+async function loadResearchPlugin(): Promise<ResearchPlugin | undefined> {
+  try {
+    return await import("@publisle/cli-research");
+  } catch (cause) {
+    if (
+      cause instanceof Error &&
+      "code" in cause &&
+      (cause.code === "ERR_MODULE_NOT_FOUND" ||
+        cause.code === "ERR_UNSUPPORTED_RESOLVE")
+    )
+      return undefined;
+    throw cause;
+  }
+}
+
+export interface CliIo {
+  readonly stdout: (text: string) => void;
+  readonly stderr: (text: string) => void;
+}
+
+const help = `Usage: publisle validate|upgrade|lock <file.json|file.md> [--config <host.mjs|host.ts>] [--format json|markdown]
+JSON-only inspection: publisle inspect|semantic <source.json> [--bundle <contracts.json>] [--mode linked|standalone]
+Reading projection: publisle reading <source.json> (not a round trip).
+Research profile (requires the optional @publisle/cli-research plugin):
+  publisle export <file.json|file.md> --to bibtex|csl-json|latex|jats|pdf|submission [--template ...] [--output <new-file>]
+  publisle bibliography <file.bib> | publisle doctor | publisle setup compiler
+Upgrade: [--output <new-file> | --in-place]. Lock: [--output <new-file>] (never in-place).
+--output refuses existing files.
+Config is trusted executable host code exporting a default CliConfig. Node >=24 required.
+Exit codes: 0 success (warnings allowed), 1 document errors, 2 usage/config/I/O errors.
+`;
+
+function diagnosticText(item: Diagnostic, file: string): string {
+  const where = item.sourceLocation;
+  return `${where?.source ?? file}${where ? `:${String(where.line)}:${String(where.column)}` : ""}: ${item.level} [${item.code}]${item.blockId ? ` (${item.blockId})` : ""}${item.profile ? ` {${item.profile}}` : ""}: ${item.message}\n`;
+}
+
+async function loadConfig(file: string | undefined): Promise<CliConfig> {
+  if (!file) return {};
+  const imported: unknown = await import(pathToFileURL(resolve(file)).href);
+  if (
+    !isPlainObject(imported) &&
+    !(typeof imported === "object" && imported !== null)
+  )
+    throw new Error("Config must export a default CliConfig object.");
+  const config: unknown = (imported as Record<string, unknown>)["default"];
+  if (!isPlainObject(config))
+    throw new Error("Config must export a default CliConfig object.");
+  const preparation = config["prepare"];
+  if (
+    preparation !== undefined &&
+    (!isPlainObject(preparation) ||
+      typeof (preparation["registry"] as { get?: unknown } | undefined)?.get !==
+        "function")
+  )
+    throw new Error(
+      "config.prepare must provide a registry created with createRegistry().",
+    );
+  if (
+    isPlainObject(preparation) &&
+    preparation["unknownBlocks"] !== undefined &&
+    preparation["unknownBlocks"] !== "preserve" &&
+    preparation["unknownBlocks"] !== "error"
+  )
+    throw new Error("config.prepare.unknownBlocks must be preserve or error.");
+  const markdown = config["markdown"];
+  if (
+    markdown !== undefined &&
+    (!isPlainObject(markdown) ||
+      (markdown["codecs"] !== undefined && !Array.isArray(markdown["codecs"])))
+  )
+    throw new Error("config.markdown must contain an optional codecs array.");
+  return config;
+}
+
+async function replaceSource(
+  file: string,
+  original: string,
+  output: string,
+): Promise<void> {
+  const stat = await lstat(file);
+  if (!stat.isFile() || stat.nlink !== 1)
+    throw new Error(
+      "--in-place requires a regular non-symlink file with one hard link.",
+    );
+  const temporary = await mkdtemp(join(dirname(file), ".publisle-upgrade-"));
+  const staged = join(temporary, "source");
+  try {
+    await writeFile(staged, output, { flag: "wx", mode: stat.mode & 0o777 });
+    await chmod(staged, stat.mode & 0o777);
+    const current = await lstat(file);
+    if (
+      current.dev !== stat.dev ||
+      current.ino !== stat.ino ||
+      current.nlink !== 1 ||
+      !current.isFile() ||
+      (await readFile(file, "utf8")) !== original
+    )
+      throw new Error(
+        "Source changed while upgrading; refusing to overwrite it.",
+      );
+    await rename(staged, file);
+  } finally {
+    await unlink(staged).catch((cause: unknown) => {
+      if (!(
+        typeof cause === "object" &&
+        cause !== null &&
+        "code" in cause &&
+        cause.code === "ENOENT"
+      ))
+        throw cause;
+    });
+    await rmdir(temporary);
+  }
+}
+
+/** Optional Node-only runner. Validation and preview never invoke a write operation. */
+export async function runCli(
+  args: readonly string[],
+  io: CliIo,
+): Promise<number> {
+  if (args.length === 1 && (args[0] === "--help" || args[0] === "-h")) {
+    io.stdout(help);
+    return 0;
+  }
+  try {
+    const command = args[0];
+    if (isResearchCommand(command)) {
+      const plugin = await loadResearchPlugin();
+      if (plugin === undefined) {
+        io.stderr(
+          `publisle: ${command} belongs to the Publisle Research profile. Install @publisle/cli-research alongside @publisle/cli to use it.\n`,
+        );
+        return 2;
+      }
+      return await plugin.runResearchCommand(command, args, io, {
+        loadConfig: (file) => loadConfig(file),
+        diagnosticText,
+      });
+    }
+    if (command === "reading") {
+      if (args.length !== 2 || !args[1] || args[1].startsWith("-"))
+        throw new Error("reading requires only canonical source.json");
+      const source = parseDocument(parseJson(await readFile(resolve(args[1]))));
+      const result = toReadingMarkdown(source);
+      for (const item of result.diagnostics)
+        io.stderr(diagnosticText(item, args[1]));
+      if (result.markdown === undefined) return 1;
+      io.stdout(result.markdown);
+      return 0;
+    }
+    if (command === "inspect" || command === "semantic") {
+      const file = args[1];
+      if (!file || file.startsWith("-"))
+        throw new Error("Inspection requires canonical source.json");
+      let bundleFile: string | undefined;
+      let mode: "linked" | "standalone" = "linked";
+      const seen = new Set<string>();
+      for (let index = 2; index < args.length; index += 2) {
+        const key = args[index];
+        const value = args[index + 1];
+        if (!key || seen.has(key) || !value || value.startsWith("-"))
+          throw new Error("Invalid or duplicate inspection option");
+        seen.add(key);
+        if (key === "--bundle") bundleFile = value;
+        else if (
+          key === "--mode" &&
+          (value === "linked" || value === "standalone")
+        )
+          mode = value;
+        else
+          throw new Error(
+            "Inspection accepts only --bundle and --mode linked|standalone; no executable config",
+          );
+      }
+      const source = parseJson(await readFile(resolve(file)));
+      const bundle = bundleFile
+        ? await validateContractBundle(
+            parseJson(await readFile(resolve(bundleFile))),
+          )
+        : undefined;
+      const options = { mode, offline: true, ...(bundle ? { bundle } : {}) };
+      const output =
+        command === "inspect"
+          ? await inspectDocument(source, options)
+          : await exportSemanticDocument(source, options);
+      io.stdout(JSON.stringify(output, null, 2) + "\n");
+      return 0;
+    }
+    if (command !== "validate" && command !== "upgrade" && command !== "lock")
+      throw new Error(
+        "Expected validate, upgrade, lock, inspect, semantic, or reading. Research commands (export, bibliography, doctor, setup) require @publisle/cli-research.",
+      );
+    let file: string | undefined;
+    let configFile: string | undefined;
+    let outputFile: string | undefined;
+    let format: "json" | "markdown" | undefined;
+    let inPlace = false;
+    const seen = new Set<string>();
+    for (let index = 1; index < args.length; index++) {
+      const arg = args[index];
+      if (arg === undefined) continue;
+      if (!arg.startsWith("-")) {
+        if (file) throw new Error("Only one input file is supported.");
+        file = arg;
+        continue;
+      }
+      if (seen.has(arg)) throw new Error(`Duplicate option ${arg}.`);
+      seen.add(arg);
+      if (arg === "--in-place") {
+        inPlace = true;
+        continue;
+      }
+      if (arg !== "--config" && arg !== "--output" && arg !== "--format")
+        throw new Error(`Unknown option ${arg}.`);
+      const value = args[++index];
+      if (!value || value.startsWith("-"))
+        throw new Error(`Missing value for ${arg}.`);
+      if (arg === "--config") configFile = value;
+      if (arg === "--output") outputFile = value;
+      if (arg === "--format") {
+        if (value !== "json" && value !== "markdown")
+          throw new Error("--format must be json or markdown.");
+        format = value;
+      }
+    }
+    if (!file) throw new Error("An input file is required.");
+    if (command === "validate" && (outputFile || inPlace))
+      throw new Error("validate does not accept write options.");
+    if (command === "lock" && inPlace)
+      throw new Error(
+        "lock preserves the original source: use stdout preview or --output <new-file>.",
+      );
+    if (outputFile && inPlace)
+      throw new Error("Choose --output or --in-place, not both.");
+    file = resolve(file);
+    if (outputFile && resolve(outputFile) === file)
+      throw new Error("Use --in-place to authorize replacing the input.");
+    if (!format) {
+      const extension = extname(file).toLowerCase();
+      if (extension === ".json") format = "json";
+      else if (extension === ".md" || extension === ".markdown")
+        format = "markdown";
+      else
+        throw new Error(
+          "Unknown file extension; provide --format json|markdown.",
+        );
+    }
+    const bytes = await readFile(file);
+    let original: string;
+    try {
+      original = new TextDecoder("utf-8", {
+        fatal: true,
+        ignoreBOM: true,
+      }).decode(bytes);
+    } catch {
+      io.stderr(
+        `${file}: error [invalid-json-unicode]: Input is not valid UTF-8.\n`,
+      );
+      return 1;
+    }
+    let config = await loadConfig(configFile);
+    if (config.contractBundle !== undefined) {
+      const bundle = await validateContractBundle(config.contractBundle);
+      config = {
+        ...config,
+        prepare: {
+          ...(config.prepare ?? {
+            registry: createRegistry(coreBlockDefinitions),
+          }),
+          contractPins: bundle.contracts.map((entry) => ({
+            type: entry.contract.identity.type,
+            schemaVersion: entry.contract.identity.schemaVersion,
+            id: entry.id,
+            digest: entry.digest,
+          })),
+        },
+      };
+    }
+    const operation = {
+      format,
+      sourceName: file,
+      config,
+    };
+    const result =
+      command === "lock"
+        ? await lockSource(original, operation)
+        : processSource(original, { ...operation, command });
+    for (const item of result.diagnostics)
+      io.stderr(diagnosticText(item, file));
+    if (result.diagnostics.some(({ level }) => level === "error")) return 1;
+    if (command === "validate") {
+      io.stderr(`${file}: valid\n`);
+      return 0;
+    }
+    if (result.output === undefined)
+      throw new Error("Upgrade produced no output.");
+    if (inPlace) await replaceSource(file, original, result.output);
+    else if (outputFile)
+      await writeFile(resolve(outputFile), result.output, { flag: "wx" });
+    else io.stdout(result.output);
+    return 0;
+  } catch (cause) {
+    io.stderr(
+      `publisle: ${cause instanceof Error ? cause.message : "CLI operation failed."}\n${help}`,
+    );
+    return 2;
+  }
+}