arcshape 0.0.0-stage → 0.1.0

package/bin/confluence.mjs

@@ -0,0 +1,263 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { JSDOM } from "jsdom";
+import createDOMPurify from "dompurify";
+import { marked } from "marked";
+import { loadDocs } from "../tools/arc42-site/loadDocs.mjs";
+
+const window = new JSDOM("").window;
+const DOMPurify = createDOMPurify(window);
+
+export async function runConfluenceSync(options) {
+  if (!options.baseUrl) throw new Error("--base-url is required");
+  if (!options.pageId) throw new Error("--page-id is required");
+  const emailEnv = options.emailEnv ?? "CONFLUENCE_EMAIL";
+  const tokenEnv = options.tokenEnv ?? "CONFLUENCE_API_TOKEN";
+  const email = process.env[emailEnv];
+  const token = process.env[tokenEnv];
+  if (!email || !token)
+    throw new Error(
+      `set both ${emailEnv} and ${tokenEnv} environment variables before connecting`,
+    );
+
+  const baseUrl = parseBaseUrl(options.baseUrl);
+  const docsDir = join(process.cwd(), options.docs ?? "docs/architecture");
+  const docs = await loadDocs(docsDir);
+  const html = await renderPage(docs);
+  const targetDigest = digest(html);
+  const manifestPath = join(
+    process.cwd(),
+    ".arcshape",
+    "confluence-sync",
+    `${safePageId(options.pageId)}.json`,
+  );
+  const previous = await readManifest(manifestPath);
+  const auth = `Basic ${Buffer.from(`${email}:${token}`).toString("base64")}`;
+  const endpoint = new URL(
+    `${baseUrl.pathname.replace(/\/$/, "")}/api/v2/pages/${encodeURIComponent(options.pageId)}`,
+    baseUrl.origin,
+  );
+  endpoint.searchParams.set("body-format", "storage");
+
+  const page = await getPage(endpoint, auth);
+  if (
+    !page ||
+    String(page.id) !== String(options.pageId) ||
+    !page.title ||
+    !Number.isInteger(page.version?.number)
+  )
+    throw new Error("Confluence returned an incomplete page response");
+  const currentHtml = page.body?.storage?.value ?? "";
+  const currentDigest = digest(currentHtml);
+
+  if (currentDigest === targetDigest) {
+    if (!options.dryRun)
+      await writeManifest(manifestPath, {
+        pageId: String(page.id),
+        digest: targetDigest,
+      });
+    printResult({
+      action: options.dryRun ? "dry-run-unchanged" : "unchanged",
+      pageId: String(page.id),
+      title: page.title,
+      baseUrl: baseUrl.origin,
+      sections: docs.sections.length,
+    });
+    return { exitCode: 0 };
+  }
+
+  if (previous && previous.digest !== currentDigest) {
+    printResult({
+      action: "conflict",
+      pageId: String(page.id),
+      title: page.title,
+      reason:
+        "the Confluence page changed since ArcShape last synchronized it; review the remote edits before syncing",
+    });
+    return { exitCode: 1 };
+  }
+  if (!previous && !isBlankHtml(currentHtml)) {
+    printResult({
+      action: "conflict",
+      pageId: String(page.id),
+      title: page.title,
+      reason:
+        "the selected page already has content and is not managed by ArcShape; select a blank page to initialize synchronization",
+    });
+    return { exitCode: 1 };
+  }
+
+  if (options.dryRun) {
+    printResult({
+      action: "dry-run-update",
+      pageId: String(page.id),
+      title: page.title,
+      baseUrl: baseUrl.origin,
+      sections: docs.sections.length,
+      contentBytes: Buffer.byteLength(html),
+    });
+    return { exitCode: 0 };
+  }
+
+  const updateEndpoint = new URL(
+    `${baseUrl.pathname.replace(/\/$/, "")}/api/v2/pages/${encodeURIComponent(options.pageId)}`,
+    baseUrl.origin,
+  );
+  const updateResponse = await fetch(updateEndpoint, {
+    method: "PUT",
+    headers: {
+      Accept: "application/json",
+      Authorization: auth,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      id: String(page.id),
+      status: page.status ?? "current",
+      title: page.title,
+      body: { representation: "storage", value: html },
+      version: {
+        number: page.version.number + 1,
+        message: "Synchronized from ArcShape Markdown",
+      },
+    }),
+    signal: AbortSignal.timeout(30_000),
+  });
+  if (!updateResponse.ok)
+    throw new Error(
+      `Confluence page update failed: HTTP ${updateResponse.status}`,
+    );
+
+  const updatedPage = await getPage(endpoint, auth);
+  if (updatedPage.version.number !== page.version.number + 1) {
+    printResult({
+      action: "conflict",
+      pageId: String(page.id),
+      title: page.title,
+      reason:
+        "the Confluence page changed during synchronization; review the remote version before retrying",
+    });
+    return { exitCode: 1 };
+  }
+  const syncedDigest = digest(updatedPage.body?.storage?.value ?? html);
+  await writeManifest(manifestPath, {
+    pageId: String(updatedPage.id),
+    digest: syncedDigest,
+  });
+  printResult({
+    action: "updated",
+    pageId: String(page.id),
+    title: page.title,
+    baseUrl: baseUrl.origin,
+    sections: docs.sections.length,
+    contentBytes: Buffer.byteLength(html),
+    version: updatedPage.version.number,
+  });
+  return { exitCode: 0 };
+}
+
+async function getPage(endpoint, auth) {
+  const response = await fetch(endpoint, {
+    headers: { Accept: "application/json", Authorization: auth },
+    signal: AbortSignal.timeout(30_000),
+  });
+  if (!response.ok)
+    throw new Error(`Confluence page lookup failed: HTTP ${response.status}`);
+  return response.json();
+}
+
+async function renderPage(docs) {
+  const parts = [`<h1>${escapeHtml(docs.readme.title)}</h1>`];
+  for (const section of docs.sections) {
+    parts.push(`<h2>${escapeHtml(section.title)}</h2>`);
+    parts.push(await marked.parse(section.body));
+  }
+  const sanitized = DOMPurify.sanitize(parts.join("\n"), {
+    ALLOW_DATA_ATTR: false,
+  });
+  return sanitized.replace(/\s+$/, "");
+}
+
+function parseBaseUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("--base-url must be a valid HTTPS URL");
+  }
+  if (
+    url.protocol !== "https:" ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash
+  )
+    throw new Error(
+      "--base-url must be HTTPS and cannot contain credentials or query parameters",
+    );
+  url.pathname = url.pathname.replace(/\/$/, "");
+  return url;
+}
+
+async function readManifest(path) {
+  try {
+    const manifest = JSON.parse(await readFile(path, "utf8"));
+    if (
+      manifest.version !== 1 ||
+      typeof manifest.digest !== "string" ||
+      !/^sha256:[a-f\d]{64}$/.test(manifest.digest)
+    )
+      throw new Error("invalid manifest format");
+    return manifest;
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw new Error(`cannot read Confluence sync manifest: ${error.message}`);
+  }
+}
+
+async function writeManifest(path, manifest) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(
+    path,
+    `${JSON.stringify({ version: 1, ...manifest }, null, 2)}\n`,
+    { mode: 0o600 },
+  );
+}
+
+function digest(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+function safePageId(value) {
+  if (!/^[a-zA-Z0-9_-]+$/.test(value))
+    throw new Error(
+      "--page-id may contain only letters, numbers, hyphens, and underscores",
+    );
+  return value;
+}
+
+function isBlankHtml(value) {
+  return (
+    value
+      .replace(/<[^>]*>/g, "")
+      .replace(/&nbsp;|&#160;|\u00a0/gi, "")
+      .trim() === ""
+  );
+}
+
+function escapeHtml(value) {
+  return value.replace(/[&<>"']/g, (character) => {
+    const entities = {
+      "&": "&amp;",
+      "<": "&lt;",
+      ">": "&gt;",
+      '"': "&quot;",
+      "'": "&#39;",
+    };
+    return entities[character];
+  });
+}
+
+function printResult(result) {
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}

package/bin/init.mjs

@@ -0,0 +1,160 @@
+import { lstat, readdir, readFile, mkdir, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep, join } from "node:path";
+
+export async function runInit(args, { packageRoot }) {
+  const options = parseOptions(args);
+  if (options.help) {
+    process.stdout.write(
+      `Usage: arcshape init [--target <directory>] [--dry-run]\n\n`,
+    );
+    process.stdout.write(
+      `Create the Markdown arc42 structure and install Codex and Claude workflows.\n`,
+    );
+    process.stdout.write(
+      `Files with different existing content are left untouched and reported.\n`,
+    );
+    return { exitCode: 0 };
+  }
+
+  const targetRoot = resolve(process.cwd(), options.target ?? ".");
+  const templatesRoot = join(packageRoot, "templates", "architecture");
+  const architectureFiles = await collectFiles(templatesRoot);
+  const assistantFiles = await collectFiles(
+    join(packageRoot, "templates", "assistants"),
+  );
+  const files = [
+    ...architectureFiles.map((file) => ({
+      ...file,
+      destinationPath: join("docs", "architecture", file.relativePath),
+    })),
+    ...assistantFiles.map((file) => ({
+      ...file,
+      destinationPath: file.relativePath,
+    })),
+  ];
+  const written = [];
+  const unchanged = [];
+  const conflicts = [];
+
+  for (const template of files) {
+    const destination = resolve(targetRoot, template.destinationPath);
+    if (!isInside(targetRoot, destination)) {
+      conflicts.push({
+        path: destination,
+        reason: "resolved outside the selected target directory",
+      });
+      continue;
+    }
+    if (await hasSymlinkInPath(targetRoot, destination)) {
+      conflicts.push({
+        path: relative(targetRoot, destination),
+        reason: "a path component is a symbolic link",
+      });
+      continue;
+    }
+
+    const content = await readFile(template.source, "utf8");
+    if (options.dryRun) {
+      unchanged.push({
+        path: relative(targetRoot, destination),
+        reason: "would be created",
+      });
+      continue;
+    }
+
+    try {
+      const existing = await readFile(destination, "utf8");
+      if (existing === content)
+        unchanged.push({
+          path: relative(targetRoot, destination),
+          reason: "already up to date",
+        });
+      else
+        conflicts.push({
+          path: relative(targetRoot, destination),
+          reason: "file already exists with different content",
+        });
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      await mkdir(dirname(destination), { recursive: true });
+      try {
+        await writeFile(destination, content, { encoding: "utf8", flag: "wx" });
+        written.push(relative(targetRoot, destination));
+      } catch (writeError) {
+        if (writeError.code !== "EEXIST") throw writeError;
+        conflicts.push({
+          path: relative(targetRoot, destination),
+          reason: "file appeared during initialization",
+        });
+      }
+    }
+  }
+
+  process.stdout.write(
+    `${options.dryRun ? "Planned" : "Created"} ${written.length || (options.dryRun ? unchanged.length : 0)} file(s).\n`,
+  );
+  for (const path of written) process.stdout.write(`  created  ${path}\n`);
+  for (const item of unchanged)
+    process.stdout.write(`  unchanged ${item.path} (${item.reason})\n`);
+  for (const item of conflicts)
+    process.stderr.write(
+      `  conflict ${item.path}: ${item.reason}; review or move the file, then run arcshape init again.\n`,
+    );
+  if (conflicts.length)
+    process.stderr.write(`No conflicting file was overwritten.\n`);
+  return { exitCode: conflicts.length ? 1 : 0, written, unchanged, conflicts };
+}
+
+function parseOptions(args) {
+  const options = { dryRun: false, help: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--help" || arg === "-h") options.help = true;
+    else if (arg === "--dry-run") options.dryRun = true;
+    else if (arg === "--target" || arg === "-C") {
+      const value = args[index + 1];
+      if (!value || value.startsWith("-"))
+        throw new Error(`${arg} requires a directory path`);
+      options.target = value;
+      index += 1;
+    } else throw new Error(`Unknown init option: ${arg}`);
+  }
+  return options;
+}
+
+async function collectFiles(root, parent = "") {
+  const entries = await readdir(join(root, parent), { withFileTypes: true });
+  const files = [];
+  for (const entry of entries.sort((left, right) =>
+    left.name.localeCompare(right.name),
+  )) {
+    const child = join(parent, entry.name);
+    if (entry.isDirectory()) files.push(...(await collectFiles(root, child)));
+    else if (entry.isFile())
+      files.push({ source: join(root, child), relativePath: child });
+  }
+  return files;
+}
+
+function isInside(root, path) {
+  const rel = relative(root, path);
+  return (
+    rel === "" ||
+    (!isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`))
+  );
+}
+
+async function hasSymlinkInPath(root, destination) {
+  const parts = relative(root, destination).split(sep);
+  let current = root;
+  for (const part of parts) {
+    current = join(current, part);
+    try {
+      if ((await lstat(current)).isSymbolicLink()) return true;
+    } catch (error) {
+      if (error.code === "ENOENT") return false;
+      throw error;
+    }
+  }
+  return false;
+}

package/bin/product-citations.mjs

@@ -0,0 +1,104 @@
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { access } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+export async function verifyProductCitations({
+  repositoryRoot,
+  docsDir,
+  productShapeCliPath,
+}) {
+  const modelRoot = resolve(repositoryRoot, "docs", "product", "model");
+  try {
+    await access(modelRoot);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return {
+        status: "skipped",
+        reason: "No docs/product/model directory was found.",
+        citations: [],
+        diagnostics: [],
+        summary: { total: 0 },
+      };
+    }
+    throw error;
+  }
+
+  const cliPath = productShapeCliPath ?? findProductShapeCli(repositoryRoot);
+  if (!cliPath) {
+    return {
+      status: "unavailable",
+      reason:
+        "A ProductShape model is present, but @prodshape/cli is not installed in this repository. Install it or run `prodshape citations verify` directly.",
+      citations: [],
+      diagnostics: [],
+      summary: { total: 0 },
+    };
+  }
+
+  const relativeDocsDir = relative(repositoryRoot, docsDir);
+  const target =
+    relativeDocsDir === "" ||
+    (!isAbsolute(relativeDocsDir) &&
+      relativeDocsDir !== ".." &&
+      !relativeDocsDir.startsWith(`..${sep}`))
+      ? relativeDocsDir || "."
+      : docsDir;
+  const result = spawnSync(
+    process.execPath,
+    [
+      cliPath,
+      "citations",
+      "verify",
+      target,
+      "--root",
+      repositoryRoot,
+      "--format",
+      "json",
+    ],
+    { cwd: repositoryRoot, encoding: "utf8", maxBuffer: 16 * 1024 * 1024 },
+  );
+
+  if (result.error) {
+    return {
+      status: "unavailable",
+      reason: `Could not run ProductShape citation verification: ${result.error.message}`,
+      citations: [],
+      diagnostics: [],
+      summary: { total: 0 },
+    };
+  }
+
+  let report;
+  try {
+    report = JSON.parse(result.stdout);
+  } catch {
+    return {
+      status: "invalid",
+      reason:
+        result.stderr?.trim() ||
+        "ProductShape citation verification did not return valid JSON.",
+      citations: [],
+      diagnostics: [],
+      summary: { total: 0 },
+    };
+  }
+
+  return {
+    status: result.status === 0 ? "verified" : "invalid",
+    reason:
+      result.status === 0 ? undefined : result.stderr?.trim() || undefined,
+    citations: report.citations ?? [],
+    diagnostics: report.diagnostics ?? [],
+    summary: report.summary ?? { total: report.citations?.length ?? 0 },
+  };
+}
+
+function findProductShapeCli(repositoryRoot) {
+  try {
+    const require = createRequire(resolve(repositoryRoot, "package.json"));
+    return require.resolve("@prodshape/cli/dist/bin.js");
+  } catch {
+    return undefined;
+  }
+}