open-agreements
Version:
Open-source legal template filling CLI and library
199 lines • 8.09 kB
JavaScript
/**
* Shared content-listing module (open-agreements#635).
*
* Canonical helpers for enumerating the repository's non-template first-class
* legal content — practice guides, reviewer checklists, and law surveys — as a
* flat, deterministic catalog with stable IDs. Used by:
* - MCP `tools.ts` (`list_content` / `get_content`, via dynamic import or npm
* dependency), alongside `template-listing.ts` for templates
* - future hosted-MCP parity in the openagreements.org deploy (which already
* consumes `template-listing.ts` the same way)
*
* The content lives as markdown bundles at the repository root
* (`practice-guides/`, `checklists/`, `surveys/` — the product-line-first
* views; the topic-first `legal-practice-library/` duplicates the same
* documents and is intentionally NOT indexed to keep IDs unique). These
* directories are part of the git repository but are NOT shipped in the npm
* package (`files` in package.json), so callers must treat "no content roots
* present" as a valid runtime state, reported by
* `listDocContentTypesAvailable()`.
*/
import { existsSync, readdirSync, readFileSync } from 'node:fs';
import { join, relative, resolve, sep } from 'node:path';
import yaml from 'js-yaml';
import { getPackageRoot } from '../utils/paths.js';
/** Repository directory backing each markdown-bundle content type. */
export const DOC_CONTENT_DIRS = {
practice_guide: 'practice-guides',
checklist: 'checklists',
survey: 'surveys',
};
export const DOC_CONTENT_TYPES = Object.keys(DOC_CONTENT_DIRS);
// ---------------------------------------------------------------------------
// Internals
// ---------------------------------------------------------------------------
/**
* One path segment of a doc slug. Deliberately strict (lowercase kebab, no
* dots) so IDs can never traverse outside the content roots.
*/
const SLUG_SEGMENT_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
/** Files that are navigation/changelog scaffolding, not content documents. */
const NON_DOCUMENT_BASENAMES = new Set(['index.md', 'log.md']);
const JURISDICTION_ROOTS = new Set(['us', 'worldwide']);
function isValidSlugPath(segments) {
return segments.length >= 2 && segments.every((segment) => SLUG_SEGMENT_PATTERN.test(segment));
}
function parseFrontmatter(text) {
const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
if (!match)
return {};
try {
const parsed = yaml.load(match[1]);
if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
return parsed;
}
}
catch {
// Unparseable frontmatter → fall back to heading-derived metadata.
}
return {};
}
function firstHeading(text) {
const match = /^# +(.+)$/m.exec(text);
if (!match)
return null;
// Strip footnote markers like `[^about]` that decorate projected headings.
return match[1].replace(/\[\^[^\]]*\]/g, '').trim() || null;
}
function asString(value) {
return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
}
function asTags(value) {
if (!Array.isArray(value))
return [];
return value.filter((tag) => typeof tag === 'string');
}
/** Recursively collect document files under `dir`, as root-relative segment arrays. */
function walkDocuments(dir, prefix = []) {
let entries;
try {
entries = readdirSync(dir, { withFileTypes: true });
}
catch {
return [];
}
const results = [];
for (const entry of [...entries].sort((a, b) => a.name.localeCompare(b.name))) {
if (entry.isDirectory()) {
if (!SLUG_SEGMENT_PATTERN.test(entry.name))
continue;
results.push(...walkDocuments(join(dir, entry.name), [...prefix, entry.name]));
continue;
}
if (!entry.isFile())
continue;
if (!entry.name.endsWith('.md') || NON_DOCUMENT_BASENAMES.has(entry.name))
continue;
const slug = entry.name.slice(0, -'.md'.length);
if (!SLUG_SEGMENT_PATTERN.test(slug))
continue;
results.push([...prefix, slug]);
}
return results;
}
function deriveJurisdiction(segments) {
// segments are the path parts after the topic, e.g. ['us', 'california'].
if (segments.length === 0 || !JURISDICTION_ROOTS.has(segments[0]))
return null;
return segments.join('/');
}
function buildItem(type, segments, contentRoot) {
// Every document lives at least one level under a topic directory.
if (!isValidSlugPath(segments))
return null;
const repoPath = `${DOC_CONTENT_DIRS[type]}/${segments.join('/')}.md`;
const absolutePath = join(contentRoot, repoPath);
let text;
try {
text = readFileSync(absolutePath, 'utf-8');
}
catch {
return null;
}
const frontmatter = parseFrontmatter(text);
const title = asString(frontmatter.title) ?? firstHeading(text) ?? segments[segments.length - 1];
return {
content_id: `${type}/${segments.join('/')}`,
type,
title,
description: asString(frontmatter.description),
topic: segments[0],
jurisdiction: deriveJurisdiction(segments.slice(1)),
format: 'markdown',
source_url: asString(frontmatter.resource),
updated_at: asString(frontmatter.timestamp),
tags: asTags(frontmatter.tags),
repo_path: repoPath,
};
}
// ---------------------------------------------------------------------------
// Public API
// ---------------------------------------------------------------------------
/**
* Which markdown-bundle content types are servable from `contentRoot` (the
* package root by default). The npm package does not ship these directories,
* so an installed-package runtime typically returns `[]` — callers should
* surface that as "content unavailable in this runtime", not as empty content.
*/
export function listDocContentTypesAvailable(contentRoot) {
const root = resolve(contentRoot ?? getPackageRoot());
return DOC_CONTENT_TYPES.filter((type) => existsSync(join(root, DOC_CONTENT_DIRS[type])));
}
/**
* List every practice guide, checklist, and survey document as a flat catalog,
* sorted lexicographically by `content_id` (deterministic order). Missing
* content directories contribute zero items.
*/
export function listDocContentItems(contentRoot) {
const root = resolve(contentRoot ?? getPackageRoot());
const items = [];
for (const type of DOC_CONTENT_TYPES) {
const typeRoot = join(root, DOC_CONTENT_DIRS[type]);
if (!existsSync(typeRoot))
continue;
for (const segments of walkDocuments(typeRoot)) {
const item = buildItem(type, segments, root);
if (item)
items.push(item);
}
}
items.sort((a, b) => a.content_id.localeCompare(b.content_id));
return items;
}
/**
* Resolve one content ID (e.g. `checklist/safes/yc-post-money-safe-valuation-cap`)
* to its full canonical document. Returns undefined for unknown IDs, IDs of the
* wrong shape, and anything that would escape the content roots.
*/
export function findDocContentItem(contentId, contentRoot) {
const root = resolve(contentRoot ?? getPackageRoot());
const [type, ...segments] = contentId.split('/');
if (!DOC_CONTENT_TYPES.includes(type))
return undefined;
if (!isValidSlugPath(segments))
return undefined;
const typeRoot = resolve(join(root, DOC_CONTENT_DIRS[type]));
const filePath = resolve(join(typeRoot, `${segments.join('/')}.md`));
const rel = relative(typeRoot, filePath);
if (rel.startsWith('..') || rel.startsWith(sep))
return undefined;
if (NON_DOCUMENT_BASENAMES.has(`${segments[segments.length - 1]}.md`))
return undefined;
if (!existsSync(filePath))
return undefined;
const item = buildItem(type, segments, root);
if (!item)
return undefined;
return { ...item, markdown: readFileSync(filePath, 'utf-8') };
}
//# sourceMappingURL=content-listing.js.map