Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

4.6 KB
Raw Blame
#!/usr/bin/env node
// Combine every markdown file under docs/ into a single navigable file (docs/ALL.md).
// One-time snapshot generator: originals are never modified. Re-run manually to refresh.
//   node scripts/combine-docs.mjs
import { readFileSync, writeFileSync } from 'node:fs';
import { execSync } from 'node:child_process';
import { dirname, relative, resolve, sep } from 'node:path';

const ROOT = process.cwd();
const DOCS_DIR = 'docs';
const OUT = `${DOCS_DIR}/ALL.md`;

// ALL.md ships to the public site as /docs/ALL.md, so it must never absorb the
// operator-only subtrees that vite's copy-static-docs plugin deliberately keeps
// out of dist/: the ops runbooks name the GCP project, its service accounts, and
// which env vars gate which routes, and the security reviews describe attacks
// against live code. Keep this set in sync with PRIVATE_DOCS in vite.config.js.
const PRIVATE_DOCS = new Set(['internal', 'ops', 'security']);

// Group by the first path segment under docs/ ("root" for docs/*.md directly).
const groupOf = (p) => {
  const parts = relative(DOCS_DIR, p).split(sep);
  return parts.length > 1 ? parts[0] : '(top level)';
};

// Collect all markdown under docs/, excluding the generated output itself
// and the repo-wide EVERYTHING.md aggregate (scripts/combine-everything.mjs).
const files = execSync(
  `find ${DOCS_DIR} -name '*.md' -not -name 'ALL.md' -not -name 'EVERYTHING.md'`,
  { cwd: ROOT },
)
  .toString()
  .trim()
  .split('\n')
  .map((p) => p.replace(/^\.\//, ''))
  .filter(Boolean)
  .filter((p) => !PRIVATE_DOCS.has(groupOf(p)))
  .sort();

const sections = files.map((path, i) => {
  const anchor = `sec-${String(i + 1).padStart(3, '0')}`;
  const body = readFileSync(path, 'utf8').replace(/\s+$/, '');
  return { path, anchor, body, group: groupOf(path) };
});

// Build the grouped table of contents.
const groups = [...new Set(sections.map((s) => s.group))];
const tocLines = [];
for (const g of groups) {
  tocLines.push(`\n### ${g}\n`);
  for (const s of sections.filter((x) => x.group === g)) {
    const label = relative(DOCS_DIR, s.path);
    tocLines.push(`- [${label}](#${s.anchor})`);
  }
}

const totalBytes = sections.reduce((n, s) => n + Buffer.byteLength(s.body), 0);
const stamp = new Date().toISOString().slice(0, 10);

const header = `<!-- GENERATED by scripts/combine-docs.mjs — do not edit by hand. Edit the source files under docs/ and re-run. -->
# three.ws — Combined Documentation

> Single-file snapshot of every document under [\`docs/\`](.). Generated ${stamp} from **${sections.length} files** (~${Math.round(totalBytes / 1024)} KB).
> The individual source files remain the canonical, editable copies — this file is a read-only aggregate.

## Table of contents
${tocLines.join('\n')}

---
`;

// Source files link relative to their own directory (../wallet/01-balance.md is
// valid from docs/agent-abilities/), but ALL.md lives at docs/ALL.md, so raw
// concatenation breaks every such link. Rebase each relative link: to the
// section anchor when the target is another combined doc, otherwise to a path
// relative to docs/. Fenced code blocks are left untouched.
const anchorByAbsPath = new Map(sections.map((s) => [resolve(ROOT, s.path), `#${s.anchor}`]));
const docsAbs = resolve(ROOT, DOCS_DIR);

const rewriteLinks = (body, sourcePath) => {
  const srcDir = resolve(ROOT, dirname(sourcePath));
  let inFence = false;
  return body
    .split('\n')
    .map((line) => {
      if (/^\s*(```|~~~)/.test(line)) {
        inFence = !inFence;
        return line;
      }
      if (inFence) return line;
      return line.replace(/(\]\()([^)\s]+)(\))/g, (whole, open, target, close) => {
        if (/^([a-z][a-z0-9+.-]*:|#|\/)/i.test(target)) return whole;
        const [filePart, fragment] = target.split('#');
        let decoded;
        try {
          decoded = decodeURIComponent(filePart);
        } catch {
          return whole;
        }
        const abs = resolve(srcDir, decoded);
        const anchor = anchorByAbsPath.get(abs);
        if (anchor && !fragment) return `${open}${anchor}${close}`;
        const rebased = relative(docsAbs, abs).split(sep).join('/');
        return `${open}${rebased}${fragment ? `#${fragment}` : ''}${close}`;
      });
    })
    .join('\n');
};

const bodyOut = sections
  .map(
    (s) =>
      `<a id="${s.anchor}"></a>\n\n> **Source:** \`${s.path}\` · [↑ table of contents](#table-of-contents)\n\n${rewriteLinks(s.body, s.path)}`,
  )
  .join('\n\n---\n\n');

writeFileSync(`${ROOT}/${OUT}`, `${header}\n${bodyOut}\n`);
console.log(`Wrote ${OUT}: ${sections.length} files, ${Math.round(totalBytes / 1024)} KB combined.`);