@twango/twiki 0.0.0-stage → 0.1.1

package/cli/runtime.ts

@@ -0,0 +1,385 @@
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import {
+  parseProjectConfig,
+  resolveProject,
+  writeProjectSiteConfig,
+  type ResolvedProject,
+} from "../site/tooling/lib/project-config";
+
+export interface PreparedProject {
+  projectRoot: string;
+  workDir: string;
+  outputDir: string;
+  env: Record<string, string>;
+}
+export interface PrepareOptions {
+  projectRoot?: string;
+  configFile?: string;
+  environment?: NodeJS.ProcessEnv;
+  /** Override only for package integration fixtures. */
+  engineDirectory?: string;
+  /** Override only for isolated installer fixtures. */
+  installDependencies?: (workDir: string) => void;
+}
+const packageRoot = fileURLToPath(new URL("../", import.meta.url));
+const engineDirectories = [
+  "src",
+  "tooling",
+  "worker",
+  "assets",
+  "static",
+  "migrations",
+  "database",
+];
+const engineFiles = [
+  "package.json",
+  "bun.lock",
+  "svelte.config.js",
+  "vite.config.ts",
+  "tsconfig.json",
+  "wrangler.jsonc",
+  "_headers",
+  "_redirects",
+  "drizzle.config.ts",
+];
+const safeRelative = (file: string) =>
+  file !== "" &&
+  !path.isAbsolute(file) &&
+  !file.includes("\\") &&
+  file.split("/").every((part) => part !== "" && part !== "." && part !== "..");
+function directory(root: string, target: string) {
+  const relative = path.relative(root, target);
+  if (
+    relative === ".." ||
+    relative.startsWith(".." + path.sep) ||
+    path.isAbsolute(relative)
+  )
+    throw new Error("Runtime path escapes its consumer directory");
+  for (const part of relative.split(path.sep).filter(Boolean)) {
+    root = path.join(root, part);
+    const stat = lstatSync(root, { throwIfNoEntry: false });
+    if (stat && (!stat.isDirectory() || realpathSync(root) !== root))
+      throw new Error("Runtime directories must not be symlinks");
+    if (!stat) mkdirSync(root);
+  }
+}
+function writeRuntime(root: string, file: string, bytes: string | Uint8Array) {
+  if (!safeRelative(file)) throw new Error("Unsafe runtime filename");
+  const target = path.join(root, file);
+  directory(root, path.dirname(target));
+  const stat = lstatSync(target, { throwIfNoEntry: false });
+  if (stat && (!stat.isFile() || realpathSync(target) !== target))
+    throw new Error("Runtime files must be regular");
+  const value = Buffer.from(bytes);
+  if (stat?.size === value.length && readFileSync(target).equals(value)) return;
+  const temporary = target + ".twiki-tmp-" + process.pid;
+  try {
+    writeFileSync(temporary, value);
+    renameSync(temporary, target);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+function inventory(source: string) {
+  const files = engineFiles.filter((file) =>
+    existsSync(path.join(source, file)),
+  );
+  const walk = (relative: string) => {
+    const absolute = path.join(source, relative);
+    if (!existsSync(absolute)) return;
+    for (const entry of readdirSync(absolute, { withFileTypes: true }).sort(
+      (a, b) => a.name.localeCompare(b.name),
+    )) {
+      if (entry.name === "node_modules" || entry.name === ".DS_Store") continue;
+      const file = relative + "/" + entry.name;
+      if (
+        file === "src/lib/generated" ||
+        file.startsWith("static/_") ||
+        file === "static/.wrangler"
+      )
+        continue;
+      if (entry.isSymbolicLink())
+        throw new Error("Packaged engine files must not be symlinks");
+      if (entry.isDirectory()) walk(file);
+      else if (entry.isFile()) files.push(file);
+    }
+  };
+  for (const folder of engineDirectories) walk(folder);
+  return [...new Set(files)].sort();
+}
+function installEngineDependencies(
+  root: string,
+  environment: NodeJS.ProcessEnv,
+) {
+  const modules = path.join(root, "node_modules");
+  directory(root, modules);
+  const contained = (file: string) => {
+    const relative = path.relative(modules, file);
+    return (
+      relative !== ".." &&
+      !relative.startsWith(".." + path.sep) &&
+      !path.isAbsolute(relative)
+    );
+  };
+  // Retire links from older CLI staging without following or mutating their targets.
+  // Existing consumer-owned Vite caches and isolated package installs stay intact.
+  const retireLinks = (folder: string, nested = false) => {
+    for (const entry of readdirSync(folder, { withFileTypes: true })) {
+      const file = path.join(folder, entry.name);
+      if (entry.isSymbolicLink()) {
+        if (!existsSync(file) || !contained(realpathSync(file))) rmSync(file);
+      } else if (
+        !nested &&
+        entry.isDirectory() &&
+        (entry.name.startsWith("@") || entry.name === ".bin")
+      )
+        retireLinks(file, true);
+    }
+  };
+  retireLinks(modules);
+  const installed = spawnSync(
+    process.execPath,
+    [
+      "install",
+      "--frozen-lockfile",
+      "--ignore-scripts",
+      "--backend",
+      "copyfile",
+      "--silent",
+    ],
+    {
+      cwd: root,
+      env: { ...process.env, ...environment },
+      encoding: "utf8",
+      maxBuffer: 16 * 1024 * 1024,
+    },
+  );
+  if (installed.error)
+    throw new Error(
+      `Unable to install the frozen Twiki engine: ${installed.error.message}`,
+    );
+  if (installed.status !== 0)
+    throw new Error(
+      `Frozen Twiki engine dependency installation failed: ${installed.stderr.trim() || "bun install exited unsuccessfully"}`,
+    );
+}
+export function wranglerConfiguration(project: ResolvedProject) {
+  const supplied = project.cloudflare ?? {};
+  const rawVars = supplied.vars;
+  if (
+    rawVars !== undefined &&
+    (!rawVars || typeof rawVars !== "object" || Array.isArray(rawVars))
+  )
+    throw new Error("cloudflare.vars must be an object");
+  const bindings = Array.isArray(supplied.d1_databases)
+    ? supplied.d1_databases
+    : [];
+  const vars = {
+    ORIGIN: project.site.url,
+    TWIKI_SITE_NAME: project.site.name,
+    TWIKI_SITE_DESCRIPTION: project.site.description,
+    TWIKI_AUTH_MODE: bindings.some(
+      (binding) =>
+        binding &&
+        typeof binding === "object" &&
+        (binding as { binding?: string }).binding === "DB",
+    )
+      ? "github"
+      : "none",
+    DISABLE_ANALYTICS: project.analytics ? "false" : "true",
+    ...(project.analytics
+      ? {
+          TWIKI_ANALYTICS_SITE_ID: project.analytics.siteId,
+          TWIKI_ANALYTICS_ENDPOINT: project.analytics.endpoint ?? "",
+        }
+      : {}),
+    ...(rawVars as Record<string, string> | undefined),
+  };
+  return {
+    name: "twiki",
+    compatibility_date: "2026-06-07",
+    compatibility_flags: ["nodejs_compat"],
+    d1_databases: [],
+    workers_dev: vars.TWIKI_AUTH_MODE === "none",
+    preview_urls: false,
+    routes: [],
+    ...supplied,
+    vars,
+    main: "build/.svelte-kit/worker.js",
+    assets: {
+      binding: "ASSETS",
+      directory: "build/.svelte-kit/cloudflare",
+      html_handling: "drop-trailing-slash",
+      not_found_handling: "404-page",
+      run_worker_first: true,
+    },
+  };
+}
+/** Copies maintained engine code; package installation and source vault remain read-only. */
+export function prepareProject(options: PrepareOptions = {}): PreparedProject {
+  const environment = options.environment ?? process.env;
+  const projectRoot = realpathSync(
+    path.resolve(
+      options.projectRoot ?? environment.TWIKI_PROJECT_ROOT ?? process.cwd(),
+    ),
+  );
+  const state = path.join(projectRoot, ".twiki");
+  const workDir = path.join(state, "site");
+  const requested = options.configFile ?? environment.TWIKI_CONFIG_FILE;
+  const configFile = requested
+    ? path.resolve(projectRoot, requested)
+    : path.join(projectRoot, "twiki.config.json");
+  const raw = existsSync(configFile)
+    ? parseProjectConfig(JSON.parse(readFileSync(configFile, "utf8")))
+    : { version: 1 as const };
+  if (requested && !existsSync(configFile))
+    throw new Error("The requested Twiki config does not exist");
+  const inputEnvironment = {
+    ...environment,
+    TWIKI_PROJECT_ROOT: projectRoot,
+    TWIKI_CONFIG_FILE: existsSync(configFile) ? configFile : undefined,
+  };
+  const project = resolveProject(workDir, projectRoot, inputEnvironment);
+  if (
+    !existsSync(project.contentDir) ||
+    !lstatSync(project.contentDir).isDirectory()
+  )
+    throw new Error("The content directory does not exist");
+  directory(projectRoot, state);
+  const lock = path.join(state, "prepare.lock");
+  try {
+    mkdirSync(lock);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST")
+      throw new Error(
+        "Another Twiki command is preparing this project; retry when it finishes",
+      );
+    throw error;
+  }
+  try {
+    const source = realpathSync(
+      options.engineDirectory ?? path.join(packageRoot, "site"),
+    );
+    const files = inventory(source);
+    directory(projectRoot, workDir);
+    const previousFile = path.join(state, "engine.json");
+    let previous: string[] = [];
+    if (existsSync(previousFile)) {
+      const saved = JSON.parse(readFileSync(previousFile, "utf8"));
+      if (
+        !Array.isArray(saved.files) ||
+        !saved.files.every(
+          (file: unknown) => typeof file === "string" && safeRelative(file),
+        )
+      )
+        throw new Error("Invalid runtime source inventory");
+      previous = saved.files;
+    }
+    for (const file of files)
+      if (
+        ![
+          "src/lib/site-config.json",
+          "src/lib/analytics-config.json",
+          "src/lib/auth-config.json",
+          "wrangler.jsonc",
+        ].includes(file)
+      )
+        writeRuntime(workDir, file, readFileSync(path.join(source, file)));
+    for (const file of previous)
+      if (!files.includes(file)) {
+        directory(workDir, path.dirname(path.join(workDir, file)));
+        rmSync(path.join(workDir, file), { force: true });
+      }
+    (
+      options.installDependencies ??
+      ((runtime) => installEngineDependencies(runtime, environment))
+    )(workDir);
+    const modules = path.join(workDir, "node_modules");
+    directory(workDir, modules);
+    writeRuntime(state, "config.json", JSON.stringify(raw, null, 2) + "\n");
+    writeProjectSiteConfig(workDir, project);
+    writeRuntime(
+      workDir,
+      "src/lib/analytics-config.json",
+      JSON.stringify(project.analytics ?? null, null, 2) + "\n",
+    );
+    const wrangler = wranglerConfiguration(project);
+    writeRuntime(
+      workDir,
+      "src/lib/auth-config.json",
+      JSON.stringify(
+        { enabled: wrangler.vars.TWIKI_AUTH_MODE === "github" },
+        null,
+        2,
+      ) + "\n",
+    );
+    writeRuntime(
+      workDir,
+      "wrangler.jsonc",
+      JSON.stringify(wrangler, null, 2) + "\n",
+    );
+    writeRuntime(
+      state,
+      "engine.json",
+      JSON.stringify({ schema: 1, files }, null, 2) + "\n",
+    );
+    return {
+      projectRoot,
+      workDir,
+      outputDir: path.join(state, "output"),
+      env: {
+        TWIKI_PROJECT_ROOT: projectRoot,
+        TWIKI_CONFIG_FILE: path.join(state, "config.json"),
+        TWIKI_CONTENT_DIR: project.contentDir,
+        TWIKI_SITE_DIR: workDir,
+        TWIKI_DEPENDENCY_DIR: modules,
+        TWIKI_DEPENDENCY_PATHS: JSON.stringify([modules]),
+      },
+    };
+  } finally {
+    rmSync(lock, { recursive: true, force: true });
+  }
+}
+/** A stable output alias avoids copying every asset after an already successful build. */
+export function publishOutput(
+  project: PreparedProject,
+  target: "cloudflare" | "static",
+) {
+  const source = path.join(
+    project.workDir,
+    "build/.svelte-kit",
+    ...(target === "static" ? ["cloudflare", "_published"] : []),
+  );
+  if (!existsSync(source))
+    throw new Error("The build did not produce the requested output");
+  const stat = lstatSync(project.outputDir, { throwIfNoEntry: false });
+  if (stat && !stat.isSymbolicLink())
+    throw new Error(
+      "Refusing to replace an existing non-symlink output directory",
+    );
+  const temporary = project.outputDir + ".tmp-" + process.pid;
+  try {
+    symlinkSync(
+      path.relative(path.dirname(project.outputDir), source),
+      temporary,
+      "dir",
+    );
+    renameSync(temporary, project.outputDir);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}

package/cli/twiki.ts

@@ -0,0 +1,305 @@
+#!/usr/bin/env bun
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { prepareProject, publishOutput, type PreparedProject } from "./runtime";
+import { resolveProject } from "../site/tooling/lib/project-config";
+
+export const help = `twiki <command> [options]
+
+  dev                         Start the development server
+  check                       Check types, links, targets, and diagrams
+  build --target cloudflare   Build a complete Cloudflare Worker (default)
+  build --target static       Export public static pages
+  preview                     Preview the Cloudflare build locally
+  deploy                      Upload the existing Cloudflare build
+  prepare [--json]            Prepare the consumer-owned .twiki/site runtime
+  exec -- <Bun arguments>     Run engine tooling with the resolved configuration
+  init                        Create twiki.config.json (never overwrites)
+
+  --project <directory>       Consumer root (default: current directory)
+  --config <file>             Explicit declarative JSON configuration
+  --                          Pass remaining arguments to dev/preview/exec
+`;
+export function argumentsFor(argv: string[]): {
+  command: string;
+  projectRoot?: string;
+  configFile?: string;
+  target: "cloudflare" | "static";
+  json: boolean;
+  extra: string[];
+} {
+  const command = argv[0] ?? "help";
+  if (["--help", "-h", "help"].includes(command))
+    return {
+      command: "help",
+      target: "cloudflare" as const,
+      json: false,
+      extra: [] as string[],
+    };
+  if (["--version", "-v"].includes(command))
+    return {
+      command: "version",
+      target: "cloudflare" as const,
+      json: false,
+      extra: [] as string[],
+    };
+  if (
+    ![
+      "dev",
+      "check",
+      "build",
+      "preview",
+      "deploy",
+      "prepare",
+      "exec",
+      "init",
+    ].includes(command)
+  )
+    throw new Error("Unknown command; run twiki --help");
+  let projectRoot: string | undefined;
+  let configFile: string | undefined;
+  let target: "cloudflare" | "static" = "cloudflare";
+  let json = false;
+  const extra: string[] = [];
+  for (let i = 1; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--") {
+      extra.push(...argv.slice(i + 1));
+      break;
+    }
+    if (arg === "--json" && command === "prepare") json = true;
+    else if (["--project", "--config", "--target"].includes(arg)) {
+      const value = argv[++i];
+      if (!value || value.startsWith("--"))
+        throw new Error("Missing option value");
+      if (arg === "--project") projectRoot = value;
+      else if (arg === "--config") configFile = value;
+      else {
+        if (command !== "build" || !["cloudflare", "static"].includes(value))
+          throw new Error("Build target must be cloudflare or static");
+        target = value as "cloudflare" | "static";
+      }
+    } else if (command === "dev" || command === "preview") extra.push(arg);
+    else throw new Error("Unsupported argument; run twiki --help");
+  }
+  if (extra.length && !["dev", "preview", "exec"].includes(command))
+    throw new Error("This command does not accept passthrough arguments");
+  if (command === "exec" && !extra.length)
+    throw new Error("Use twiki exec -- <Bun arguments>");
+  return { command, projectRoot, configFile, target, json, extra };
+}
+export function invocation(
+  command: string,
+  project: PreparedProject,
+  extra: string[] = [],
+) {
+  const bin = (name: string) =>
+    path.join(project.workDir, "node_modules", ".bin", name);
+  if (command === "dev") return [bin("vite"), "dev", ...extra];
+  if (command === "check") return [process.execPath, "run", "check"];
+  if (command === "build") return [process.execPath, "tooling/build.ts"];
+  if (command === "preview") {
+    if (
+      extra.some(
+        (argument) =>
+          argument === "-r" ||
+          argument.startsWith("-r=") ||
+          argument === "--remote" ||
+          argument.startsWith("--remote=") ||
+          argument === "--local=false",
+      )
+    )
+      throw new Error("Preview supports local Workers only");
+    const option = (name: string) => {
+      const index = extra.findIndex(
+        (argument) => argument === name || argument.startsWith(`${name}=`),
+      );
+      if (index < 0) return undefined;
+      const value = extra[index].startsWith(`${name}=`)
+        ? extra[index].slice(name.length + 1)
+        : extra[index + 1];
+      if (!value || value.startsWith("--"))
+        throw new Error(`Missing ${name} value`);
+      return value;
+    };
+    const port = option("--port") ?? "4173";
+    if (!/^\d+$/.test(port) || Number(port) < 1 || Number(port) > 65535)
+      throw new Error("Preview port must be between 1 and 65535");
+    const ip = option("--ip") ?? "127.0.0.1";
+    const protocol = option("--local-protocol") ?? "http";
+    if (protocol !== "http" && protocol !== "https")
+      throw new Error("Preview protocol must be http or https");
+    const host =
+      ip === "0.0.0.0"
+        ? "127.0.0.1"
+        : ip === "::"
+          ? "[::1]"
+          : ip.includes(":") && !ip.startsWith("[")
+            ? `[${ip}]`
+            : ip;
+    let origin: URL;
+    try {
+      origin = new URL(`${protocol}://${host}:${port}`);
+    } catch {
+      throw new Error("Invalid preview IP or hostname");
+    }
+    if (
+      origin.username ||
+      origin.password ||
+      origin.pathname !== "/" ||
+      origin.search ||
+      origin.hash
+    )
+      throw new Error("Invalid preview IP or hostname");
+    let explicitOrigin = false,
+      inVariables = false;
+    for (const argument of extra) {
+      if (argument === "--var") {
+        inVariables = true;
+        continue;
+      }
+      if (argument.startsWith("--var=")) {
+        explicitOrigin ||= argument.startsWith("--var=ORIGIN:");
+        inVariables = true;
+        continue;
+      }
+      if (argument.startsWith("-")) inVariables = false;
+      if (inVariables && argument.startsWith("ORIGIN:")) explicitOrigin = true;
+    }
+    return [
+      process.execPath,
+      "tooling/wrangler.ts",
+      "dev",
+      ...(option("--persist-to")
+        ? []
+        : ["--persist-to", "build/.wrangler/state"]),
+      ...(option("--port") ? [] : ["--port", port]),
+      ...(option("--ip") ? [] : ["--ip", ip]),
+      ...(!explicitOrigin ? ["--var", `ORIGIN:${origin.origin}`] : []),
+      ...extra,
+    ];
+  }
+  if (command === "deploy")
+    return [process.execPath, "tooling/deploy.ts", "--upload"];
+  if (command === "exec") return [process.execPath, ...extra];
+  throw new Error("Unsupported engine invocation");
+}
+async function run(binary: string, args: string[], project: PreparedProject) {
+  const child = spawn(binary, args, {
+    cwd: project.workDir,
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      ...project.env,
+      PATH: [
+        path.join(project.workDir, "node_modules/.bin"),
+        path.dirname(process.execPath),
+        process.env.PATH,
+      ]
+        .filter(Boolean)
+        .join(path.delimiter),
+    },
+  });
+  const interrupt = (signal: NodeJS.Signals) => child.kill(signal);
+  const sigint = () => interrupt("SIGINT");
+  const sigterm = () => interrupt("SIGTERM");
+  process.on("SIGINT", sigint);
+  process.on("SIGTERM", sigterm);
+  try {
+    await new Promise<void>((resolve, reject) => {
+      child.once("error", reject);
+      child.once("close", (code, signal) =>
+        code === 0
+          ? resolve()
+          : reject(
+              new Error("Engine command failed (" + (code ?? signal) + ")"),
+            ),
+      );
+    });
+  } finally {
+    process.off("SIGINT", sigint);
+    process.off("SIGTERM", sigterm);
+  }
+}
+export async function main(argv = process.argv.slice(2)) {
+  const options = argumentsFor(argv);
+  if (options.command === "help") {
+    console.log(help);
+    return;
+  }
+  if (options.command === "version") {
+    console.log(
+      JSON.parse(
+        readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+      ).version,
+    );
+    return;
+  }
+  if (options.command === "init") {
+    const file = path.resolve(
+      options.projectRoot ?? process.cwd(),
+      options.configFile ?? "twiki.config.json",
+    );
+    writeFileSync(
+      file,
+      JSON.stringify(
+        {
+          version: 1,
+          contentDir: ".",
+          discovery: "filesystem",
+          publication: "private",
+          site: { name: "My notes", title: "My notes" },
+        },
+        null,
+        2,
+      ) + "\n",
+      { flag: "wx" },
+    );
+    console.log("Created twiki.config.json");
+    return;
+  }
+  const project = prepareProject(options);
+  if (options.command === "prepare") {
+    console.log(
+      options.json
+        ? JSON.stringify(project)
+        : "Twiki runtime ready: " +
+            path.relative(process.cwd(), project.workDir),
+    );
+    return;
+  }
+  const resolved = resolveProject(project.workDir, project.projectRoot, {
+    ...process.env,
+    ...project.env,
+  });
+  if (
+    options.command === "build" &&
+    options.target === "static" &&
+    resolved.publication !== "public"
+  )
+    throw new Error(
+      'Static export requires publication: "public"; private content needs Cloudflare authentication',
+    );
+  if (options.command === "deploy" && !resolved.cloudflare)
+    throw new Error("Deployment requires explicit cloudflare configuration");
+  const [binary, ...args] = invocation(options.command, project, options.extra);
+  if (options.command === "build" && options.target === "static")
+    args.push("--static");
+  await run(binary, args, project);
+  if (options.command === "build") {
+    publishOutput(project, options.target);
+    console.log(
+      "Output: " + path.relative(project.projectRoot, project.outputDir),
+    );
+  }
+}
+if (import.meta.main)
+  try {
+    await main();
+  } catch (error) {
+    console.error(
+      "twiki: " + (error instanceof Error ? error.message : "command failed"),
+    );
+    process.exitCode = 1;
+  }