Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
import { readdir, readFile } from 'node:fs/promises';
import { join, posix } from 'node:path';
/** Keep canonical plugin output intact; only organize pages for the agent's reader. */
export async function readMarkdownPages(directory: string) {
const pages = new Map<string, string>();
for (const entry of (await readdir(directory, { recursive: true })).sort()) {
if (entry.endsWith('.md')) {
pages.set(
entry.replaceAll('\\', '/'),
await readFile(join(directory, entry), 'utf8')
);
}
}
return pages;
}
/**
* One SDK entity: when to use it, the compact index of what it declares, and
* the `@agent` guidance its declarations carry about how that area of Macro
* works, when they carry any.
*/
export type EntityDocs = {
name: string;
description: string;
guide?: string;
index: string;
};
/** `@routing` and `@agent` text, as `renderSdkDocs` collects it. */
export type AgentNotes = {
module: string;
name: string;
routing?: string;
guide?: string;
};
/** The heading a namespace's reference gives its `@agent` guidance. */
const GUIDE_HEADING = '## Agent guidance';
/**
* The agent reads the SDK in two steps: an entity's index lists its classes,
* methods and types by symbol, and each symbol's own reference is read on
* request. Symbols are a class (`Task`), one of its methods (`Task.update`) or
* a type (`CreateTaskOptions`); a name two pages share is qualified by its
* directory (`storage.Message`).
*/
export type SdkDocs = {
entities: EntityDocs[];
symbols: Record<string, string>;
};
const LINK = /\[([^\]]*)\]\(([^)]+\.md)(?:#([^)]*))?\)/g;
/**
* Package the TypeDoc pages as entities. `directories` are the entity
* directories under `src/entities/`; each entity's description is the one
* `@routing` sentence among its declarations, and its guide every `@agent`
* block among them. A missing or doubled routing sentence, or a note outside
* every entity, fails the build.
*/
export function packageEntityDocs(
sourcePages: ReadonlyMap<string, string>,
directories: readonly string[],
notes: readonly AgentNotes[]
): SdkDocs {
const pages = new Map(
[...sourcePages].filter(([path]) => !path.endsWith('/README.md'))
);
const core = [
'src/macro/',
'src/config/',
'src/mentions/',
'src/entities/entity/',
'src/entities/sharing/',
'src/entities/messages/',
'src/entities/reference/',
'src/utils/',
'src/events/',
];
const groups = [
...directories.map((directory) => ({
name:
directory === 'foreign'
? 'foreignEntities'
: directory.replace(/-([a-z])/g, (_, letter: string) =>
letter.toUpperCase()
),
prefixes: [`src/entities/${directory}/`],
})),
{ name: 'core', prefixes: core },
];
// Each note belongs to the entity whose directories hold its module.
const unclaimed = new Set(notes);
const notesOf = (prefixes: readonly string[]) =>
notes.filter((note) => {
const owned = prefixes.some((prefix) =>
`${note.module}/`.startsWith(prefix)
);
if (owned) unclaimed.delete(note);
return owned;
});
const sections = groups.map(({ name, prefixes }) => {
const own = notesOf(prefixes);
const routing = own.flatMap((note) => (note.routing ? [note.routing] : []));
if (routing.length !== 1)
throw new Error(
`SDK entity ${name} needs exactly one @routing sentence ("Use when …; not …"), found ${routing.length}`
);
const guides = own.flatMap((note) => (note.guide ? [note.guide] : []));
return {
name,
prefixes,
description: routing[0] ?? '',
...(guides.length ? { guide: guides.join('\n\n') } : {}),
};
});
if (unclaimed.size)
throw new Error(
`@routing or @agent outside every SDK entity: ${[...unclaimed]
.map((note) => `${note.module}#${note.name}`)
.join(', ')}`
);
// A namespace's own reference carries its guidance too, for ReadCodeDocs.
const guideByPage = new Map(
notes.flatMap((note) =>
note.guide ? [[`${note.module}/classes/${note.name}.md`, note.guide]] : []
)
);
const resolve = (from: string, target: string) =>
posix.normalize(
posix.join(posix.dirname(from), decodeURIComponent(target))
);
// Every page an entity declares, and every wire contract those reach.
const documented = new Set<string>();
const owned = sections.map(({ name, prefixes }) => {
const own = [...pages.keys()].filter((path) =>
prefixes.some((prefix) => path.startsWith(prefix))
);
if (!own.length) throw new Error(`TypeDoc generated no pages for ${name}`);
const reached = new Set(own);
// Follow the plugin's links, not TypeScript syntax. Shared wire definitions
// may recurse or reference one another; a Set handles cycles deterministically.
for (const path of reached) {
for (const match of (pages.get(path) ?? '').matchAll(LINK)) {
const target = resolve(path, match[2] ?? '');
if (!pages.has(target))
throw new Error(`Broken TypeDoc link: ${path} -> ${target}`);
if (target.startsWith('generated/')) reached.add(target);
}
}
for (const path of reached) documented.add(path);
return own.sort();
});
// A page is known by its name. An SDK class or type keeps it when no other
// SDK page shares it; a wire contract keeps it only when no page at all does.
const named = new Map<string, string[]>();
for (const path of documented) {
const name = pageName(path);
named.set(name, [...(named.get(name) ?? []), path]);
}
const symbolOf = new Map<string, string>();
for (const [name, paths] of named) {
const sdk = paths.filter((path) => path.startsWith('src/'));
for (const path of paths) {
const bare = path.startsWith('src/')
? sdk.length === 1
: paths.length === 1;
symbolOf.set(path, bare ? name : `${pageGroup(path)}.${name}`);
}
}
if (new Set(symbolOf.values()).size !== symbolOf.size)
throw new Error('Two TypeDoc pages share a qualified symbol');
// Links name the symbol they point at, as ReadCodeDocs takes it.
const relink = (path: string, markdown: string) =>
markdown
.replace(LINK, (_whole, label: string, target: string, anchor) => {
const symbol = symbolOf.get(resolve(path, target));
if (!symbol) return label;
// An anchor is a member; its label keeps the member's case.
const member = anchor
? `.${label.replaceAll('`', '').split('.').pop()}`
: '';
return `\`${symbol}${member}\``;
})
// TypeDoc writes an inherited member as `[Class].[member]`.
.replace(/`([^`]+)`\.`\1\.([^`]+)`/g, '`$1.$2`');
const symbols: Record<string, string> = {};
for (const path of [...documented].sort()) {
const symbol = symbolOf.get(path) ?? '';
const markdown = relink(path, pages.get(path) ?? '');
if (!path.includes('/classes/')) {
const { header, members } = splitUnion(symbol, markdown.trim());
symbols[symbol] = header;
for (const member of members)
symbols[`${symbol}.${member.name}`] = member.markdown;
continue;
}
const { header, methods } = splitClass(markdown);
const guide = guideByPage.get(path);
symbols[symbol] = guide
? `${header}\n\n${GUIDE_HEADING}\n\n${guide}`
: header;
for (const method of methods)
symbols[`${symbol}.${method.name}`] = method.markdown;
}
// Where each namespace class is reached from: `macro.tasks`.
const accessors = new Map<string, string>();
for (const match of relink(
'src/macro/classes/Macro.md',
pages.get('src/macro/classes/Macro.md') ?? ''
).matchAll(
/^\| <a id="property-[^"]+"><\/a> `([^`]+)` \| `readonly` \| `([^`]+)`/gm
))
accessors.set(match[2] ?? '', `macro.${match[1]}`);
return {
entities: sections.map(({ name, description, guide }, index) => ({
name,
description,
...(guide ? { guide } : {}),
index: entityIndex(
name,
description,
(owned[index] ?? []).map((path) => ({
path,
symbol: symbolOf.get(path) ?? '',
markdown: relink(path, pages.get(path) ?? ''),
})),
accessors
),
})),
symbols,
};
}
function pageName(path: string) {
return posix.basename(path, '.md');
}
/** The directory that tells two same-named pages apart: a wire service or an entity. */
function pageGroup(path: string) {
const parts = path.split('/');
return parts[0] === 'generated'
? (parts[1] ?? '')
: (parts[parts.indexOf('entities') + 1] ?? parts[1] ?? '');
}
type Method = { name: string; markdown: string; inherited: boolean };
/** Largest reference ReadCodeDocs serves whole. */
const REFERENCE_BYTES = 16 * 1024;
/**
* A discriminated union too large to read at once, such as an edit operation
* vocabulary: its declaration, plus each member's fields on their own, named
* by the member's discriminator (`EditOp.setText`). Smaller pages, and unions
* whose members don't each carry a distinct string literal, stay whole.
*/
function splitUnion(symbol: string, markdown: string) {
const whole = { header: markdown, members: [] as Method[] };
if (Buffer.byteLength(markdown) <= REFERENCE_BYTES) return whole;
const [declaration = '', list] = markdown.split(/^## Union Members$/m);
if (list === undefined) return whole;
const members = list
.split(/^(?=### )/m)
.filter((block) => block.startsWith('### '))
.map((block) => {
const text = block.replace(/\n\*\*\*\s*$/, '').trim();
const literal = text.match(/`\w+`: `"([^"]+)"`/);
return { name: literal?.[1] ?? '', markdown: text, inherited: false };
});
const names = new Set(members.map((member) => member.name));
if (names.has('') || names.size !== members.length) return whole;
const index = members.map((member) => `\`${symbol}.${member.name}\``);
return {
header: `${declaration.trim()}\n\n## Union Members\n\nRead a member's fields with ReadCodeDocs: ${index.join(', ')}.`,
members: members.map((member) => ({
...member,
markdown: `# ${symbol}.${member.name}\n\n${member.markdown}`,
})),
};
}
/** A class page's own description and fields, and each method on its own. */
function splitClass(markdown: string) {
const sections = markdown.split(/^(?=## )/m);
const header = sections
.filter(
(section) =>
!section.startsWith('## Constructors') &&
!section.startsWith('## Methods')
)
.join('')
.trim();
const methods: Method[] = (
sections.find((section) => section.startsWith('## Methods')) ?? ''
)
.split(/^(?=### )/m)
.filter((block) => block.startsWith('### '))
.map((block) => {
const text = block.replace(/\n\*\*\*\s*$/, '').trim();
return {
name: (text.match(/^### (\S+?)\(\)/) ?? [])[1] ?? '',
markdown: text,
inherited: /^#### Inherited from/m.test(text),
};
})
.filter((method) => method.name);
return { header, methods };
}
/** Markdown inline code and escapes, as plain text. */
function plain(markdown: string) {
return markdown
.replace(/\*\*|`/g, '')
.replace(/\\([<>|_*[\]{}])/g, '$1')
.trim();
}
/** The first sentence of the paragraph after a heading's signature. */
function summary(markdown: string) {
const paragraph =
markdown
.split(/\n\n+/)
.slice(1)
.find(
(part) =>
!part.startsWith('>') &&
!part.startsWith('#') &&
!part.startsWith('|') &&
!part.startsWith('-')
) ?? '';
const sentence =
plain(paragraph.replace(/\n/g, ' ')).split(/(?<=\.)\s/)[0] ?? '';
return sentence.length > 160 ? `${sentence.slice(0, 157)}...` : sentence;
}
function entityIndex(
name: string,
description: string,
pages: { path: string; symbol: string; markdown: string }[],
accessors: ReadonlyMap<string, string>
) {
const lines = [
`## ${name}`,
description,
'Read any symbol below, or one a reference names, with ReadCodeDocs.',
];
const kinds: Record<string, string[]> = {};
for (const { path, symbol, markdown } of pages) {
if (!path.includes('/classes/')) {
const kind = path.includes('/functions/') ? 'Functions' : 'Types';
kinds[kind] = [...(kinds[kind] ?? []), `\`${symbol}\``];
continue;
}
const { header, methods } = splitClass(markdown);
const reach = accessors.get(symbol);
const parent = header.match(/^## Extends\n\n- `([^`]+)`/m)?.[1];
lines.push(
'',
`### ${symbol}${reach ? ` (\`${reach}\`)` : ''}`,
...[summary(header), parent && `Extends \`${parent}\`.`].filter(
(line): line is string => Boolean(line)
)
);
const fields = [
...header.matchAll(/^\| <a id="property-[^"]+"><\/a> `([^`]+)`/gm),
].map((match) => match[1]);
if (fields.length) lines.push(`Fields: ${fields.join(', ')}`);
for (const method of methods.filter((method) => !method.inherited)) {
const signature = method.markdown.match(/^> (.+)$/m)?.[1] ?? '';
const about = summary(method.markdown);
lines.push(
`- \`${symbol}.${method.name}\`: ${plain(signature)}${about ? ` — ${about}` : ''}`
);
}
}
for (const kind of ['Functions', 'Types'])
if (kinds[kind]?.length)
lines.push('', `${kind}: ${kinds[kind].join(', ')}`);
return `${lines.join('\n')}\n`;
}