@sorane/cli 0.2.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@sorane/cli",
+  "version": "0.2.0",
+  "description": "OKF-native static site generator CLI",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/masanork/sorane.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://sorane.dev",
+  "bugs": "https://github.com/masanork/sorane/issues",
+  "keywords": [
+    "ssg",
+    "static-site-generator",
+    "okf",
+    "open-knowledge-format",
+    "markdown",
+    "blog",
+    "ai-disclosure",
+    "c2pa"
+  ],
+  "files": [
+    "src"
+  ],
+  "bin": {
+    "sorane": "./src/main.ts"
+  },
+  "engines": {
+    "node": ">=23.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "prepublishOnly": "cd ../.. && npm run typecheck && npm test",
+  "dependencies": {
+    "@sorane/core": "0.2.0",
+    "@sorane/okf": "0.2.0",
+    "@sorane/search": "0.2.0",
+    "js-yaml": "^4.1.0"
+  }
+}

package/src/build.ts

@@ -0,0 +1,18 @@
+import { runBuild } from "@sorane/core";
+import { loadSoraneConfig, parseCwdFlag } from "./config-load.ts";
+
+export async function runBuildCmd(argv: string[]): Promise<void> {
+  const cwd = parseCwdFlag(argv);
+  const config = loadSoraneConfig(cwd);
+  const clean = argv.includes("--clean");
+  const result = await runBuild({
+    cwd,
+    config,
+    clean,
+    skipC2pa: argv.includes("--skip-c2pa"),
+  });
+  const secs = (result.durationMs / 1000).toFixed(1);
+  process.stdout.write(
+    `[sorane] built ${result.pages} page(s) in ${secs}s → ${config.build.out_dir}/\n`,
+  );
+}

package/src/config-load.ts

@@ -0,0 +1,28 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import yaml from "js-yaml";
+import { mergeConfig, type SoraneConfig } from "@sorane/core";
+
+export function loadSoraneConfig(cwd: string): SoraneConfig {
+  const path = resolve(cwd, "sorane.yaml");
+  if (!existsSync(path)) {
+    return mergeConfig({});
+  }
+  const raw = yaml.load(readFileSync(path, "utf8"), { schema: yaml.CORE_SCHEMA });
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("sorane.yaml must be a YAML mapping");
+  }
+  const doc = raw as Record<string, unknown>;
+  return mergeConfig({
+    site: doc.site as SoraneConfig["site"] | undefined,
+    build: doc.build as SoraneConfig["build"] | undefined,
+    fonts: doc.fonts as SoraneConfig["fonts"] | undefined,
+    search: doc.search as SoraneConfig["search"] | undefined,
+    docs: doc.docs as SoraneConfig["docs"] | undefined,
+  });
+}
+
+export function parseCwdFlag(argv: string[]): string {
+  const i = argv.indexOf("--cwd");
+  return i >= 0 && argv[i + 1] ? resolve(argv[i + 1]!) : process.cwd();
+}

package/src/index-cmd.ts

@@ -0,0 +1,52 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { buildSearchIndex, RuriEmbeddings } from "@sorane/search";
+import { loadSoraneConfig, parseCwdFlag } from "./config-load.ts";
+
+export async function runIndexCmd(argv: string[]): Promise<void> {
+  const cwd = parseCwdFlag(argv);
+  const config = loadSoraneConfig(cwd);
+  const force = argv.includes("--force");
+  const configMode = config.search.mode ?? "fts";
+  const hybrid =
+    argv.includes("--hybrid") || (argv.includes("--fts-only") ? false : configMode === "hybrid");
+  const get = (flag: string, def: string) => {
+    const i = argv.indexOf(flag);
+    return i >= 0 && argv[i + 1] ? argv[i + 1]! : def;
+  };
+  const outFlag = argv.indexOf("--out");
+  const indexPath =
+    outFlag >= 0 && argv[outFlag + 1]
+      ? resolve(cwd, argv[outFlag + 1]!)
+      : resolve(cwd, config.search.index);
+  const contentDir = resolve(cwd, config.build.content_dir);
+  const modelRoot = resolve(cwd, get("--model", config.search.model));
+  const modelId = get("--model-id", config.search.model_id);
+
+  let embeddings = null;
+  if (hybrid) {
+    const modelDir = resolve(modelRoot, modelId);
+    if (!existsSync(modelDir)) {
+      process.stderr.write(
+        `[sorane] model not found at ${modelDir}; indexing FTS-only\n` +
+          `  run: npm run fetch-model (or sorane index without --hybrid)\n`,
+      );
+    } else {
+      embeddings = new RuriEmbeddings({ modelRoot, modelId });
+    }
+  }
+
+  const result = await buildSearchIndex({
+    contentDir,
+    indexPath,
+    force,
+    embeddings,
+    onProgress: (message) => process.stdout.write(`[sorane] ${message}\n`),
+  });
+
+  process.stdout.write(
+    `[sorane] indexed ${result.chunks} chunk(s) [${result.mode}] → ${indexPath}\n` +
+      `  added=${result.added} changed=${result.changed} removed=${result.removed} unchanged=${result.unchanged}\n` +
+      (result.mode === "hybrid" ? `  vec=${result.vec}\n` : ""),
+  );
+}

package/src/main.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { runBuildCmd } from "./build.ts";
+import { runWatchCmd } from "./watch.ts";
+import { runIndexCmd } from "./index-cmd.ts";
+import { runMigrateCmd } from "./migrate.ts";
+import { runSearchCmd } from "./search-cmd.ts";
+import { runValidateCmd } from "./validate.ts";
+
+const [, , command, ...rest] = process.argv;
+
+async function main(): Promise<void> {
+  switch (command) {
+    case "build":
+      if (rest.includes("--watch")) {
+        await runWatchCmd(rest.filter((a) => a !== "--watch"));
+      } else {
+        await runBuildCmd(rest);
+      }
+      break;
+    case "watch":
+      await runWatchCmd(rest);
+      break;
+    case "validate":
+      await runValidateCmd(rest);
+      break;
+    case "migrate":
+      await runMigrateCmd(rest);
+      break;
+    case "index":
+      await runIndexCmd(rest);
+      break;
+    case "search":
+      await runSearchCmd(rest);
+      break;
+    default:
+      process.stderr.write(
+        "usage: sorane <build|validate|migrate|index|search|watch> [options]\n" +
+          "  build     --cwd <dir> [--clean] [--watch] [--skip-c2pa]\n" +
+          "  watch     --cwd <dir> [--clean]\n" +
+          "  validate  --cwd <dir>\n" +
+          "  migrate   --cwd <dir> [--dry-run] [--bump-profile 0.2]\n" +
+          "  index     --cwd <dir> [--force] [--hybrid] [--fts-only] [--out <path>] [--model <dir>] [--model-id <id>]\n" +
+          "  search    <query> [--cwd <dir>] [--type article] [--tag <slug>] [--k 10] [--json] [--fts-only]\n",
+      );
+      process.exit(command === undefined ? 0 : 1);
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+});

package/src/migrate.ts

@@ -0,0 +1,46 @@
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { migrateToOkf, parseBumpProfileArg } from "@sorane/core";
+import { loadSoraneConfig, parseCwdFlag } from "./config-load.ts";
+
+function walkMarkdown(root: string): string[] {
+  const out: string[] = [];
+  function visit(dir: string): void {
+    for (const name of readdirSync(dir).sort()) {
+      const abs = join(dir, name);
+      if (statSync(abs).isDirectory()) visit(abs);
+      else if (name.endsWith(".md")) out.push(abs);
+    }
+  }
+  visit(root);
+  return out;
+}
+
+export async function runMigrateCmd(argv: string[]): Promise<void> {
+  const cwd = parseCwdFlag(argv);
+  const config = loadSoraneConfig(cwd);
+  const contentDir = resolve(cwd, config.build.content_dir);
+  const dryRun = argv.includes("--dry-run");
+  const bumpProfile = parseBumpProfileArg(argv);
+
+  if (!existsSync(contentDir)) {
+    throw new Error(`content directory not found: ${contentDir}`);
+  }
+
+  let count = 0;
+  for (const abs of walkMarkdown(contentDir)) {
+    const rel = relative(contentDir, abs);
+    const source = readFileSync(abs, "utf8");
+    const migrated = migrateToOkf(source, rel, bumpProfile ? { bumpProfile } : undefined);
+    if (migrated !== source) {
+      count++;
+      if (dryRun) {
+        process.stdout.write(`[sorane] would migrate: ${rel}\n`);
+      } else {
+        writeFileSync(abs, migrated, "utf8");
+        process.stdout.write(`[sorane] migrated: ${rel}\n`);
+      }
+    }
+  }
+  process.stdout.write(`[sorane] ${dryRun ? "would migrate" : "migrated"} ${count} file(s)\n`);
+}

package/src/search-cmd.ts

@@ -0,0 +1,104 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { IndexStore, RuriEmbeddings, search, checkModelMismatch } from "@sorane/search";
+import { loadSoraneConfig, parseCwdFlag } from "./config-load.ts";
+
+function parseSearchArgs(argv: string[]): {
+  cwd: string;
+  query: string;
+  indexPath: string;
+  modelRoot: string;
+  modelId: string;
+  k: number;
+  docType: string;
+  tag: string;
+  json: boolean;
+  ftsOnly: boolean;
+} {
+  const cwd = parseCwdFlag(argv);
+  const config = loadSoraneConfig(cwd);
+  const get = (flag: string, def: string) => {
+    const i = argv.indexOf(flag);
+    return i >= 0 && argv[i + 1] ? argv[i + 1]! : def;
+  };
+  const query = argv.find((t, i) => !t.startsWith("--") && (i === 0 || !argv[i - 1]!.startsWith("--"))) ?? "";
+  const outFlag = argv.indexOf("--out");
+  const indexPath =
+    outFlag >= 0 && argv[outFlag + 1]
+      ? resolve(cwd, argv[outFlag + 1]!)
+      : resolve(cwd, config.search.index);
+  return {
+    cwd,
+    query,
+    indexPath,
+    modelRoot: resolve(cwd, get("--model", config.search.model)),
+    modelId: get("--model-id", config.search.model_id),
+    k: Number(get("--k", "10")) || 10,
+    docType: get("--type", ""),
+    tag: get("--tag", ""),
+    json: argv.includes("--json"),
+    ftsOnly: argv.includes("--fts-only"),
+  };
+}
+
+export async function runSearchCmd(argv: string[]): Promise<void> {
+  const args = parseSearchArgs(argv);
+  if (!args.query) {
+    process.stderr.write(
+      "usage: sorane search <query> [--cwd <dir>] [--type article] [--tag <slug>] [--k 10] [--json] [--fts-only]\n",
+    );
+    process.exit(2);
+  }
+
+  const store = new IndexStore(args.indexPath);
+  let embeddings = null;
+  if (!args.ftsOnly && store.hasVectors()) {
+    const modelDir = resolve(args.modelRoot, args.modelId);
+    if (!existsSync(modelDir)) {
+      process.stderr.write(
+        `[sorane] model not found at ${modelDir}; searching FTS-only\n`,
+      );
+    } else {
+      embeddings = new RuriEmbeddings({
+        modelRoot: args.modelRoot,
+        modelId: args.modelId,
+      });
+      const mismatch = checkModelMismatch(
+        store.readMeta(),
+        args.modelId,
+        embeddings.dimensions,
+      );
+      if (mismatch) {
+        process.stderr.write(`[sorane] warning: ${mismatch}; consider re-indexing with --force\n`);
+      }
+    }
+  }
+
+  const results = await search(store, embeddings, args.query, {
+    k: args.k,
+    filter: {
+      docType: args.docType || undefined,
+      tag: args.tag || undefined,
+    },
+    ftsOnly: args.ftsOnly,
+  });
+  store.close();
+
+  if (args.json) {
+    process.stdout.write(JSON.stringify(results, null, 2) + "\n");
+    return;
+  }
+
+  if (results.length === 0) {
+    process.stdout.write("(no results)\n");
+    return;
+  }
+
+  for (const [i, row] of results.entries()) {
+    process.stdout.write(
+      `${i + 1}. ${row.title || row.source} (${row.source}#${row.headingSlug || row.chunkIndex}) [${row.score.toFixed(4)}]\n` +
+        `   ${row.headingPath}\n` +
+        `   ${row.snippet}\n\n`,
+    );
+  }
+}

package/src/validate.ts

@@ -0,0 +1,58 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { validateDiagramAltWarnings, validateHeadingWarnings } from "@sorane/core";
+import { extract } from "@sorane/okf";
+import { validateSource } from "@sorane/okf";
+import { loadSoraneConfig, parseCwdFlag } from "./config-load.ts";
+
+function walkMarkdown(root: string): string[] {
+  const out: string[] = [];
+  function visit(dir: string): void {
+    for (const name of readdirSync(dir).sort()) {
+      const abs = join(dir, name);
+      if (statSync(abs).isDirectory()) visit(abs);
+      else if (name.endsWith(".md")) out.push(abs);
+    }
+  }
+  visit(root);
+  return out;
+}
+
+export async function runValidateCmd(argv: string[]): Promise<void> {
+  const cwd = parseCwdFlag(argv);
+  const config = loadSoraneConfig(cwd);
+  const contentDir = resolve(cwd, config.build.content_dir);
+  if (!existsSync(contentDir)) {
+    throw new Error(`content directory not found: ${contentDir}`);
+  }
+
+  let errors = 0;
+  for (const abs of walkMarkdown(contentDir)) {
+    const rel = relative(contentDir, abs);
+    const source = readFileSync(abs, "utf8");
+    const result = validateSource(rel, source);
+    for (const w of result.warnings) {
+      process.stderr.write(`[sorane] ${rel}: warning: ${w}\n`);
+    }
+    const { body } = extract(source);
+    if (body !== null) {
+      for (const w of validateDiagramAltWarnings(body, config.build.diagrams ?? {})) {
+        process.stderr.write(`[sorane] ${rel}: warning: ${w}\n`);
+      }
+      for (const w of validateHeadingWarnings(body)) {
+        process.stderr.write(`[sorane] ${rel}: warning: ${w}\n`);
+      }
+    }
+    if (!result.ok) {
+      for (const issue of result.issues) {
+        process.stderr.write(`[sorane] ${rel}: ${issue.message}\n`);
+      }
+      errors += result.issues.length;
+    }
+  }
+
+  if (errors > 0) {
+    throw new Error(`${errors} validation error(s)`);
+  }
+  process.stdout.write("[sorane] all concepts valid\n");
+}

package/src/watch.ts

@@ -0,0 +1,79 @@
+import { existsSync, watch } from "node:fs";
+import { resolve } from "node:path";
+import { runBuildCmd } from "./build.ts";
+import { loadSoraneConfig, parseCwdFlag } from "./config-load.ts";
+
+const DEBOUNCE_MS = 350;
+
+function parseWatchArgv(argv: string[]): { cwd: string; clean: boolean; buildArgv: string[] } {
+  const cwd = parseCwdFlag(argv);
+  const clean = argv.includes("--clean");
+  const buildArgv = ["--cwd", cwd];
+  if (clean) buildArgv.push("--clean");
+  return { cwd, clean, buildArgv };
+}
+
+function watchPaths(cwd: string, contentDir: string): string[] {
+  const paths = [resolve(cwd, contentDir), resolve(cwd, "sorane.yaml")];
+  const staticDir = resolve(cwd, "static");
+  if (existsSync(staticDir)) paths.push(staticDir);
+  return paths;
+}
+
+export async function runWatchCmd(argv: string[]): Promise<void> {
+  const { cwd, clean, buildArgv } = parseWatchArgv(argv);
+  const config = loadSoraneConfig(cwd);
+  const contentDir = config.build.content_dir;
+
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let building = false;
+  let pending = false;
+
+  const runOnce = async (initial: boolean): Promise<void> => {
+    if (building) {
+      pending = true;
+      return;
+    }
+    building = true;
+    try {
+      if (initial && !clean) {
+        await runBuildCmd(buildArgv);
+      } else {
+        await runBuildCmd([...buildArgv.filter((a) => a !== "--clean"), "--clean"]);
+      }
+    } catch (err) {
+      process.stderr.write(
+        `[sorane] watch build failed: ${err instanceof Error ? err.message : String(err)}\n`,
+      );
+    } finally {
+      building = false;
+      if (pending) {
+        pending = false;
+        void runOnce(false);
+      }
+    }
+  };
+
+  process.stdout.write("[sorane] watching for changes (Ctrl+C to stop)\n");
+  await runOnce(true);
+
+  const schedule = (): void => {
+    if (timer !== null) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      void runOnce(false);
+    }, DEBOUNCE_MS);
+  };
+
+  for (const target of watchPaths(cwd, contentDir)) {
+    if (!existsSync(target)) continue;
+    try {
+      watch(target, { recursive: true }, (_event, filename) => {
+        if (filename?.includes(".sorane/")) return;
+        schedule();
+      });
+    } catch {
+      watch(target, () => schedule());
+    }
+  }
+}