@justyork/repo-mind 0.3.0

package/dist/index/link-index.js

@@ -0,0 +1,150 @@
+const WIKILINK_PATTERN = /\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/g;
+export function parseWikilinkTargets(body) {
+    const targets = [];
+    for (const match of body.matchAll(WIKILINK_PATTERN)) {
+        const display = match[1]?.trim() ?? '';
+        const slugPart = match[2]?.trim() ?? display;
+        if (slugPart) {
+            targets.push(slugPart);
+        }
+    }
+    return targets;
+}
+function buildSlugLookups(docs) {
+    const slugSet = new Set(docs.map((doc) => doc.slug));
+    const titleToSlug = new Map();
+    for (const doc of docs) {
+        titleToSlug.set(doc.slug.toLowerCase(), doc.slug);
+        titleToSlug.set(doc.title.toLowerCase(), doc.slug);
+    }
+    return { slugSet, titleToSlug };
+}
+export function resolveWikilinkTarget(raw, lookups) {
+    if (lookups.slugSet.has(raw)) {
+        return { slug: raw, broken: false };
+    }
+    const byKey = lookups.titleToSlug.get(raw.toLowerCase());
+    if (byKey) {
+        return { slug: byKey, broken: false };
+    }
+    return { slug: null, broken: true };
+}
+function addBacklink(backlinks, to, entry) {
+    const list = backlinks.get(to) ?? [];
+    const duplicate = list.some((item) => item.from === entry.from && item.kind === entry.kind);
+    if (!duplicate) {
+        list.push(entry);
+        backlinks.set(to, list);
+    }
+}
+export function buildLinkIndex(docs, extraEdges = []) {
+    const lookups = buildSlugLookups(docs);
+    const edges = [...extraEdges];
+    const backlinks = new Map();
+    const brokenTargets = new Set();
+    function registerEdge(edge) {
+        edges.push(edge);
+        if (lookups.slugSet.has(edge.to)) {
+            addBacklink(backlinks, edge.to, { from: edge.from, kind: edge.kind });
+        }
+    }
+    for (const doc of docs) {
+        if (doc.contentKind !== 'markdown') {
+            continue;
+        }
+        for (const related of doc.related) {
+            if (related === doc.slug) {
+                continue;
+            }
+            const broken = !lookups.slugSet.has(related);
+            if (broken) {
+                brokenTargets.add(related);
+            }
+            registerEdge({
+                from: doc.slug,
+                to: related,
+                kind: 'related',
+                ...(broken ? { rawTarget: related } : {}),
+            });
+        }
+        for (const raw of parseWikilinkTargets(doc.body)) {
+            const resolved = resolveWikilinkTarget(raw, lookups);
+            if (resolved.broken || !resolved.slug) {
+                brokenTargets.add(raw);
+                registerEdge({
+                    from: doc.slug,
+                    to: raw,
+                    kind: 'wikilink',
+                    rawTarget: raw,
+                });
+                continue;
+            }
+            if (resolved.slug === doc.slug) {
+                continue;
+            }
+            registerEdge({
+                from: doc.slug,
+                to: resolved.slug,
+                kind: 'wikilink',
+            });
+        }
+    }
+    for (const edge of extraEdges) {
+        if (lookups.slugSet.has(edge.to)) {
+            addBacklink(backlinks, edge.to, { from: edge.from, kind: edge.kind });
+        }
+    }
+    return { edges, backlinks, brokenTargets };
+}
+export function getOutboundSlugs(snapshot, fromSlug) {
+    const seen = new Set();
+    const result = [];
+    for (const edge of snapshot.edges) {
+        if (edge.from !== fromSlug || seen.has(edge.to)) {
+            continue;
+        }
+        seen.add(edge.to);
+        result.push(edge.to);
+    }
+    return result;
+}
+export function computeLinkHealth(snapshot, docs) {
+    const inbound = new Set();
+    const outboundPairs = new Set();
+    const reversePairs = new Set();
+    for (const edge of snapshot.edges) {
+        if (edge.kind === 'parent_of') {
+            continue;
+        }
+        inbound.add(edge.to);
+        outboundPairs.add(`${edge.from}\0${edge.to}`);
+        reversePairs.add(`${edge.to}\0${edge.from}`);
+    }
+    let oneWayCount = 0;
+    for (const pair of outboundPairs) {
+        if (!reversePairs.has(pair)) {
+            oneWayCount += 1;
+        }
+    }
+    const orphanSlugs = docs.length <= 1
+        ? []
+        : docs
+            .filter((doc) => !inbound.has(doc.slug))
+            .map((doc) => doc.slug);
+    return {
+        orphanSlugs,
+        brokenTargets: [...snapshot.brokenTargets].sort(),
+        oneWayCount,
+    };
+}
+export function getBacklinksForSlug(snapshot, slug, docsBySlug) {
+    const entries = snapshot.backlinks.get(slug) ?? [];
+    return entries.map((entry) => {
+        const doc = docsBySlug.get(entry.from);
+        return {
+            slug: entry.from,
+            title: doc?.title ?? entry.from,
+            kind: entry.kind,
+        };
+    });
+}

package/dist/index/path-inference.d.ts

@@ -0,0 +1,9 @@
+import { type DocDomain, type DocType } from './types.js';
+/** Infers doc type from any path segment matching a known type folder. */
+export declare function inferTypeFromRelative(relative: string): DocType;
+/** Infers domain from the first path segment when it is a known domain id. */
+export declare function inferDomainFromRelative(relative: string): DocDomain;
+/** Resolves domain from frontmatter override or path inference. */
+export declare function resolveDomain(relative: string, explicit: unknown): DocDomain;
+/** Domain encoded in path (ignores frontmatter). */
+export declare function domainFromPath(relative: string): DocDomain;

package/dist/index/path-inference.js

@@ -0,0 +1,33 @@
+import { DIR_TO_TYPE, isDocDomain } from './types.js';
+function normalizedSegments(relative) {
+    return relative.replace(/\\/g, '/').split('/').filter(Boolean);
+}
+/** Infers doc type from any path segment matching a known type folder. */
+export function inferTypeFromRelative(relative) {
+    for (const segment of normalizedSegments(relative)) {
+        const mapped = DIR_TO_TYPE[segment];
+        if (mapped) {
+            return mapped;
+        }
+    }
+    return 'wiki-page';
+}
+/** Infers domain from the first path segment when it is a known domain id. */
+export function inferDomainFromRelative(relative) {
+    const [first] = normalizedSegments(relative);
+    if (first && isDocDomain(first)) {
+        return first;
+    }
+    return 'shared';
+}
+/** Resolves domain from frontmatter override or path inference. */
+export function resolveDomain(relative, explicit) {
+    if (typeof explicit === 'string' && isDocDomain(explicit)) {
+        return explicit;
+    }
+    return inferDomainFromRelative(relative);
+}
+/** Domain encoded in path (ignores frontmatter). */
+export function domainFromPath(relative) {
+    return inferDomainFromRelative(relative);
+}

package/dist/index/resolve-asset-href.d.ts

@@ -0,0 +1,2 @@
+/** Resolves an image/asset href to a path relative to the docs root. */
+export declare function resolveAssetRelativePath(fromDocRelative: string, href: string): string | null;

package/dist/index/resolve-asset-href.js

@@ -0,0 +1,65 @@
+import { isImageFileName } from './asset-file.js';
+function stripLinkSuffix(href) {
+    return href.split('#')[0]?.split('?')[0]?.trim() ?? '';
+}
+function isExternalHref(href) {
+    return (href.startsWith('http://') ||
+        href.startsWith('https://') ||
+        href.startsWith('mailto:') ||
+        href.startsWith('#') ||
+        href.startsWith('data:'));
+}
+function resolveRelativePath(fromDocRelative, href) {
+    const pathPart = stripLinkSuffix(href);
+    if (!pathPart || isExternalHref(pathPart)) {
+        return null;
+    }
+    const fromDir = fromDocRelative.includes('/')
+        ? fromDocRelative.slice(0, fromDocRelative.lastIndexOf('/'))
+        : '';
+    const segments = pathPart.replace(/\\/g, '/').split('/');
+    const stack = fromDir ? fromDir.split('/') : [];
+    for (const segment of segments) {
+        if (!segment || segment === '.') {
+            continue;
+        }
+        if (segment === '..') {
+            if (stack.length === 0) {
+                return null;
+            }
+            stack.pop();
+            continue;
+        }
+        stack.push(segment);
+    }
+    const resolved = stack.join('/');
+    return resolved || null;
+}
+function resolveDocsRootPath(href) {
+    let pathPart = stripLinkSuffix(href).replace(/\\/g, '/');
+    if (!pathPart || isExternalHref(pathPart) || pathPart.split('/').includes('..')) {
+        return null;
+    }
+    if (!pathPart.startsWith('/') && !pathPart.startsWith('docs/')) {
+        return null;
+    }
+    if (pathPart.startsWith('/')) {
+        pathPart = pathPart.slice(1);
+    }
+    if (pathPart.startsWith('docs/')) {
+        pathPart = pathPart.slice(5);
+    }
+    return pathPart || null;
+}
+/** Resolves an image/asset href to a path relative to the docs root. */
+export function resolveAssetRelativePath(fromDocRelative, href) {
+    const docsRoot = resolveDocsRootPath(href);
+    if (docsRoot && isImageFileName(docsRoot)) {
+        return docsRoot;
+    }
+    const relative = resolveRelativePath(fromDocRelative, href);
+    if (relative && isImageFileName(relative)) {
+        return relative;
+    }
+    return null;
+}

package/dist/index/resolve-md-href.d.ts

@@ -0,0 +1,7 @@
+export declare function readmeRelativePath(folderRelativePath: string): string;
+export declare function parseSlugFromHref(href: string): string | null;
+/** Resolves a markdown href relative to the current doc path under docs/. */
+export declare function resolveMarkdownHref(fromDocRelative: string, href: string): string | null;
+/** Resolves href as path under docs/ root (e.g. `docs/README.md`, `/adr/foo.md`). */
+export declare function resolveDocsKnowledgeHref(href: string): string | null;
+export declare function slugForMarkdownHref(fromDocRelative: string, href: string, slugByRelative: Map<string, string>): string | null;

package/dist/index/resolve-md-href.js

@@ -0,0 +1,116 @@
+export function readmeRelativePath(folderRelativePath) {
+    const base = folderRelativePath.replace(/\\/g, '/').replace(/^\/+|\/+$/g, '');
+    return base ? `${base}/README.md` : 'README.md';
+}
+export function parseSlugFromHref(href) {
+    if (!href) {
+        return null;
+    }
+    if (href.startsWith('?slug=') || href.startsWith('/?slug=')) {
+        const query = href.includes('?') ? href.slice(href.indexOf('?')) : href;
+        const slug = new URLSearchParams(query).get('slug');
+        return slug?.trim() || null;
+    }
+    try {
+        const url = new URL(href, 'http://local');
+        const slug = url.searchParams.get('slug');
+        return slug?.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+function stripLinkSuffix(href) {
+    return href.split('#')[0]?.split('?')[0]?.trim() ?? '';
+}
+function normalizeMdPath(relative) {
+    const normalized = relative.replace(/\\/g, '/').replace(/^\/+/, '');
+    if (!normalized) {
+        return '';
+    }
+    return normalized.toLowerCase().endsWith('.md') ? normalized : `${normalized}.md`;
+}
+/** Resolves a markdown href relative to the current doc path under docs/. */
+export function resolveMarkdownHref(fromDocRelative, href) {
+    const pathPart = stripLinkSuffix(href);
+    if (!pathPart || pathPart.startsWith('http://') || pathPart.startsWith('https://')) {
+        return null;
+    }
+    if (pathPart.startsWith('mailto:') || pathPart.startsWith('#')) {
+        return null;
+    }
+    const fromDir = fromDocRelative.includes('/')
+        ? fromDocRelative.slice(0, fromDocRelative.lastIndexOf('/'))
+        : '';
+    const segments = pathPart.replace(/\\/g, '/').split('/');
+    const stack = fromDir ? fromDir.split('/') : [];
+    for (const segment of segments) {
+        if (!segment || segment === '.') {
+            continue;
+        }
+        if (segment === '..') {
+            if (stack.length === 0) {
+                return null;
+            }
+            stack.pop();
+            continue;
+        }
+        stack.push(segment);
+    }
+    return normalizeMdPath(stack.join('/'));
+}
+/** Resolves href as path under docs/ root (e.g. `docs/README.md`, `/adr/foo.md`). */
+export function resolveDocsKnowledgeHref(href) {
+    let pathPart = stripLinkSuffix(href).replace(/\\/g, '/');
+    if (!pathPart || pathPart.startsWith('http://') || pathPart.startsWith('https://')) {
+        return null;
+    }
+    if (pathPart.startsWith('mailto:') || pathPart.startsWith('#')) {
+        return null;
+    }
+    if (pathPart.startsWith('/')) {
+        pathPart = pathPart.slice(1);
+    }
+    if (pathPart.startsWith('docs/')) {
+        pathPart = pathPart.slice(5);
+    }
+    if (!pathPart) {
+        return null;
+    }
+    return normalizeMdPath(pathPart);
+}
+function lookupSlugByRelative(relativePath, slugByRelative) {
+    const direct = slugByRelative.get(relativePath);
+    if (direct) {
+        return direct;
+    }
+    const lower = relativePath.toLowerCase();
+    for (const [key, slug] of slugByRelative.entries()) {
+        if (key.toLowerCase() === lower) {
+            return slug;
+        }
+    }
+    return null;
+}
+export function slugForMarkdownHref(fromDocRelative, href, slugByRelative) {
+    const fromQuery = parseSlugFromHref(href);
+    if (fromQuery) {
+        for (const slug of slugByRelative.values()) {
+            if (slug === fromQuery) {
+                return fromQuery;
+            }
+        }
+        return null;
+    }
+    const candidates = [
+        resolveMarkdownHref(fromDocRelative, href),
+        resolveDocsKnowledgeHref(href),
+    ].filter((value) => Boolean(value));
+    for (const resolved of candidates) {
+        const slug = lookupSlugByRelative(resolved, slugByRelative);
+        if (slug) {
+            return slug;
+        }
+    }
+    return null;
+}

package/dist/index/slug.d.ts

@@ -0,0 +1,5 @@
+export declare const SLUG_PATTERN: RegExp;
+export declare function isValidSlug(slug: string): boolean;
+/** Builds a stable slug from a path relative to the docs root. */
+export declare function slugFromRelativePath(relativePath: string): string;
+export declare function resolveDocPath(knowledgeRoot: string, typeDir: string, slug: string): string | null;

package/dist/index/slug.js

@@ -0,0 +1,43 @@
+import path from 'node:path';
+export const SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+export function isValidSlug(slug) {
+    return SLUG_PATTERN.test(slug);
+}
+/** Builds a stable slug from a path relative to the docs root. */
+export function slugFromRelativePath(relativePath) {
+    const normalized = relativePath
+        .replace(/\\/g, '/')
+        .replace(/\.(md|ya?ml|json)$/i, '');
+    const segments = normalized.split('/').filter(Boolean);
+    if (segments.length === 0) {
+        return 'untitled';
+    }
+    const candidates = [
+        segments.length === 1 ? segments[0] : segments.join('-'),
+        segments[segments.length - 1],
+    ];
+    for (const raw of candidates) {
+        const slug = raw
+            .toLowerCase()
+            .replace(/[^a-z0-9-]/g, '-')
+            .replace(/-+/g, '-')
+            .replace(/^-|-$/g, '');
+        if (isValidSlug(slug)) {
+            return slug;
+        }
+    }
+    return 'untitled';
+}
+export function resolveDocPath(knowledgeRoot, typeDir, slug) {
+    if (!isValidSlug(slug)) {
+        return null;
+    }
+    const candidate = path.resolve(knowledgeRoot, typeDir, `${slug}.md`);
+    const rootWithSep = knowledgeRoot.endsWith(path.sep)
+        ? knowledgeRoot
+        : `${knowledgeRoot}${path.sep}`;
+    if (!candidate.startsWith(rootWithSep)) {
+        return null;
+    }
+    return candidate;
+}

package/dist/index/types.d.ts

@@ -0,0 +1,44 @@
+export declare const DOC_TYPES: readonly ["adr", "feature-spec", "glossary-term", "open-question", "agent-instruction", "wiki-page"];
+export type DocType = (typeof DOC_TYPES)[number];
+export declare const DOC_STATUSES: readonly ["draft", "proposed", "accepted", "superseded"];
+export type DocStatus = (typeof DOC_STATUSES)[number];
+export type ContentKind = 'markdown' | 'yaml' | 'json';
+/** Business area / documentation domain (orthogonal to doc `type`). */
+export declare const DOC_DOMAINS: readonly ["product", "technical", "game-design", "analytics", "art", "narrative", "ops", "shared"];
+export type DocDomain = (typeof DOC_DOMAINS)[number];
+export declare const DOMAIN_LABELS: Record<DocDomain, string>;
+/** Default type subfolders created under each domain by `repo-mind init`. */
+export declare const DOMAIN_TYPE_DIRS: Record<DocDomain, readonly string[]>;
+export declare const TYPE_TO_DIR: Record<DocType, string>;
+export declare const DIR_TO_TYPE: Record<string, DocType>;
+export interface DocFrontmatter {
+    type: DocType;
+    slug: string;
+    status: DocStatus;
+    /** Documentation domain — product, technical, game-design, etc. */
+    domain?: DocDomain;
+    title?: string;
+    tags?: string[];
+    related?: string[];
+    owner?: string;
+    updated?: string;
+}
+export interface DocRecord {
+    path: string;
+    relativePath: string;
+    slug: string;
+    type: DocType;
+    domain: DocDomain;
+    status: DocStatus;
+    title: string;
+    tags: string[];
+    related: string[];
+    body: string;
+    frontmatter: DocFrontmatter;
+    /** True when the file has explicit RepoMind frontmatter (type field). */
+    prepared: boolean;
+    contentKind: ContentKind;
+}
+export declare function isDocType(value: unknown): value is DocType;
+export declare function isDocStatus(value: unknown): value is DocStatus;
+export declare function isDocDomain(value: unknown): value is DocDomain;

package/dist/index/types.js

@@ -0,0 +1,71 @@
+export const DOC_TYPES = [
+    'adr',
+    'feature-spec',
+    'glossary-term',
+    'open-question',
+    'agent-instruction',
+    'wiki-page',
+];
+export const DOC_STATUSES = [
+    'draft',
+    'proposed',
+    'accepted',
+    'superseded',
+];
+/** Business area / documentation domain (orthogonal to doc `type`). */
+export const DOC_DOMAINS = [
+    'product',
+    'technical',
+    'game-design',
+    'analytics',
+    'art',
+    'narrative',
+    'ops',
+    'shared',
+];
+export const DOMAIN_LABELS = {
+    product: 'Product',
+    technical: 'Technical',
+    'game-design': 'Game design',
+    analytics: 'Analytics',
+    art: 'Art',
+    narrative: 'Narrative',
+    ops: 'Operations',
+    shared: 'Shared',
+};
+/** Default type subfolders created under each domain by `repo-mind init`. */
+export const DOMAIN_TYPE_DIRS = {
+    product: ['specs', 'wiki', 'open-questions'],
+    technical: ['adr', 'specs', 'glossary', 'wiki'],
+    'game-design': ['specs', 'glossary', 'wiki'],
+    analytics: ['specs', 'wiki'],
+    art: ['wiki', 'specs'],
+    narrative: ['wiki', 'specs'],
+    ops: ['specs', 'wiki'],
+    shared: ['agents', 'glossary', 'wiki'],
+};
+export const TYPE_TO_DIR = {
+    adr: 'adr',
+    'feature-spec': 'specs',
+    'glossary-term': 'glossary',
+    'open-question': 'open-questions',
+    'agent-instruction': 'agents',
+    'wiki-page': 'wiki',
+};
+export const DIR_TO_TYPE = {
+    adr: 'adr',
+    specs: 'feature-spec',
+    glossary: 'glossary-term',
+    'open-questions': 'open-question',
+    agents: 'agent-instruction',
+    wiki: 'wiki-page',
+};
+export function isDocType(value) {
+    return typeof value === 'string' && DOC_TYPES.includes(value);
+}
+export function isDocStatus(value) {
+    return typeof value === 'string' && DOC_STATUSES.includes(value);
+}
+export function isDocDomain(value) {
+    return typeof value === 'string' && DOC_DOMAINS.includes(value);
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1 @@
+export declare function startMcpServer(): Promise<void>;