@doxbrix/doxloop 0.1.5 → 0.2.0

package/dist/project-detect.js

@@ -0,0 +1,251 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, resolve, sep } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { listFiles, pathExists } from './fs.js';
+import { ROOT_CONTENT_IGNORED_DIRECTORIES } from './project.js';
+/**
+ * Page extensions per generator when the adapter package cannot be loaded,
+ * so a folder can be inspected before anything is installed.
+ */
+export const DEFAULT_PAGE_EXTENSIONS = {
+    doxbrix: ['.md', '.mdx'],
+    docusaurus: ['.md', '.mdx'],
+    mkdocs: ['.md'],
+    sphinx: ['.rst'],
+    hugo: ['.md'],
+    vitepress: ['.md'],
+    markdoc: ['.md'],
+    nextra: ['.md', '.mdx'],
+    starlight: ['.md', '.mdx'],
+    jekyll: ['.md'],
+    static: ['.html'],
+};
+/**
+ * Recognize an existing documentation site from the files its generator
+ * needs. Detection only reads; it never writes into the folder. Order matters
+ * where markers overlap: a Docusaurus or MkDocs site may also carry a Jekyll
+ * style `_config.yml`, so the more specific generator is listed first.
+ */
+export async function detectDocumentationGenerator(root) {
+    const absolute = resolve(root);
+    const candidates = [];
+    for (const detector of DETECTORS) {
+        const candidate = await detector(absolute);
+        if (candidate && !candidates.some((item) => item.generator === candidate.generator))
+            candidates.push(candidate);
+    }
+    return { candidates, ...(candidates[0] ? { recommended: candidates[0] } : {}) };
+}
+/**
+ * Project-relative page paths under a content directory, using the
+ * generator's default extensions. Missing directories yield no pages instead
+ * of an error so an inspection can report "0 pages" for a wrong guess.
+ */
+export async function listDocumentationPageFiles(root, generator, contentDir) {
+    const absoluteRoot = resolve(root);
+    const contentRoot = contentDir ? resolve(absoluteRoot, contentDir) : absoluteRoot;
+    try {
+        if (!(await stat(contentRoot)).isDirectory())
+            return [];
+    }
+    catch {
+        return [];
+    }
+    const files = await listFiles(contentRoot, new Set(DEFAULT_PAGE_EXTENSIONS[generator]), {
+        ignoredDirectories: contentRoot === absoluteRoot ? ROOT_CONTENT_IGNORED_DIRECTORIES : new Set(['node_modules', '.git']),
+    });
+    return files.map((file) => portable(file.slice(absoluteRoot.length + 1))).sort();
+}
+const DETECTORS = [
+    detectDoxbrix,
+    detectDocusaurus,
+    detectMkDocs,
+    detectStarlight,
+    detectVitePress,
+    detectNextra,
+    detectMarkdoc,
+    detectHugo,
+    detectSphinx,
+    detectJekyll,
+];
+async function detectDoxbrix(root) {
+    for (const directory of ['', ...(await firstLevelDirectories(root))]) {
+        const marker = join(directory, 'docs.json');
+        const config = await readJsonObject(join(root, marker));
+        if (!config)
+            continue;
+        const spaces = Array.isArray(config.spaces);
+        const legacy = typeof config.title === 'string' && Array.isArray(config.navigation);
+        if (!spaces && !legacy)
+            continue;
+        const title = typeof config.name === 'string' ? config.name : typeof config.title === 'string' ? config.title : undefined;
+        return { generator: 'doxbrix', contentDir: portable(directory), markers: [portable(marker)], ...(title ? { title } : {}) };
+    }
+    return undefined;
+}
+async function detectDocusaurus(root) {
+    const marker = await firstExisting(root, ['docusaurus.config.js', 'docusaurus.config.ts', 'docusaurus.config.mjs', 'docusaurus.config.cjs']);
+    if (!marker)
+        return undefined;
+    const title = quotedValue(await readText(join(root, marker)), 'title');
+    return { generator: 'docusaurus', contentDir: 'docs', markers: [marker], ...(title ? { title } : {}) };
+}
+async function detectMkDocs(root) {
+    const marker = await firstExisting(root, ['mkdocs.yml', 'mkdocs.yaml']);
+    if (!marker)
+        return undefined;
+    const config = safeYaml(await readText(join(root, marker)));
+    const docsDir = typeof config?.docs_dir === 'string' && isSafeContentDir(config.docs_dir) ? config.docs_dir : 'docs';
+    const title = typeof config?.site_name === 'string' ? config.site_name : undefined;
+    return { generator: 'mkdocs', contentDir: portable(docsDir), markers: [marker], ...(title ? { title } : {}) };
+}
+async function detectStarlight(root) {
+    const marker = await firstExisting(root, ['astro.config.mjs', 'astro.config.js', 'astro.config.ts']);
+    if (!marker)
+        return undefined;
+    const content = await readText(join(root, marker));
+    if (!content.includes('starlight'))
+        return undefined;
+    const title = quotedValue(content, 'title');
+    return { generator: 'starlight', contentDir: 'src/content/docs', markers: [marker], ...(title ? { title } : {}) };
+}
+async function detectVitePress(root) {
+    const directories = ['docs', ...(await firstLevelDirectories(root)).filter((directory) => directory !== 'docs')];
+    for (const directory of directories) {
+        const marker = await firstExisting(root, ['config.mts', 'config.ts', 'config.js', 'config.mjs'].map((file) => join(directory, '.vitepress', file)));
+        if (!marker)
+            continue;
+        const title = quotedValue(await readText(join(root, marker)), 'title');
+        return { generator: 'vitepress', contentDir: portable(directory), markers: [portable(marker)], ...(title ? { title } : {}) };
+    }
+    return undefined;
+}
+async function detectNextra(root) {
+    const markers = [];
+    const nextConfig = await firstExisting(root, ['next.config.mjs', 'next.config.js', 'next.config.ts']);
+    if (nextConfig && (await readText(join(root, nextConfig))).includes('nextra'))
+        markers.push(nextConfig);
+    const theme = await firstExisting(root, ['theme.config.tsx', 'theme.config.jsx', 'theme.config.js']);
+    if (theme)
+        markers.push(theme);
+    if (markers.length === 0)
+        return undefined;
+    const contentDir = (await firstExisting(root, ['content', 'pages'])) ?? 'content';
+    return { generator: 'nextra', contentDir, markers };
+}
+async function detectMarkdoc(root) {
+    const marker = await firstExisting(root, ['markdoc.config.mjs', 'markdoc.config.js', 'markdoc.config.ts']);
+    if (!marker)
+        return undefined;
+    return { generator: 'markdoc', contentDir: 'docs', markers: [marker] };
+}
+async function detectHugo(root) {
+    const marker = await firstExisting(root, [
+        'hugo.toml', 'hugo.yaml', 'hugo.yml', 'hugo.json',
+        'config/_default/hugo.toml', 'config/_default/hugo.yaml', 'config/_default/hugo.yml',
+        'config/_default/config.toml', 'config/_default/config.yaml', 'config/_default/config.yml',
+    ]);
+    let content = marker ? await readText(join(root, marker)) : '';
+    let found = marker;
+    if (!found) {
+        const generic = await firstExisting(root, ['config.toml', 'config.yaml', 'config.yml']);
+        if (!generic)
+            return undefined;
+        content = await readText(join(root, generic));
+        if (!/\b(baseURL|baseurl|languageCode|theme)\b/.test(content))
+            return undefined;
+        found = generic;
+    }
+    const contentDir = tomlOrYamlValue(content, 'contentDir') ?? 'content';
+    const title = tomlOrYamlValue(content, 'title');
+    return { generator: 'hugo', contentDir: isSafeContentDir(contentDir) ? portable(contentDir) : 'content', markers: [portable(found)], ...(title ? { title } : {}) };
+}
+async function detectSphinx(root) {
+    for (const directory of ['docs', 'doc', 'source', 'docs/source', 'doc/source']) {
+        const marker = join(directory, 'conf.py');
+        if (!(await pathExists(join(root, marker))))
+            continue;
+        const title = quotedValue(await readText(join(root, marker)), 'project');
+        return { generator: 'sphinx', contentDir: directory, markers: [portable(marker)], ...(title ? { title } : {}) };
+    }
+    return undefined;
+}
+async function detectJekyll(root) {
+    if (!(await pathExists(join(root, '_config.yml'))))
+        return undefined;
+    const config = safeYaml(await readText(join(root, '_config.yml')));
+    const contentDir = (await firstExisting(root, ['_docs', 'docs'])) ?? '_docs';
+    const title = typeof config?.title === 'string' ? config.title : undefined;
+    return { generator: 'jekyll', contentDir, markers: ['_config.yml'], ...(title ? { title } : {}) };
+}
+async function firstLevelDirectories(root) {
+    try {
+        const entries = await readdir(root, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory() && !ROOT_CONTENT_IGNORED_DIRECTORIES.has(entry.name) && !entry.name.startsWith('.'))
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+async function firstExisting(root, paths) {
+    for (const path of paths)
+        if (await pathExists(join(root, path)))
+            return path;
+    return undefined;
+}
+async function readText(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+async function readJsonObject(path) {
+    const text = await readText(path);
+    if (!text.trim())
+        return undefined;
+    try {
+        const parsed = JSON.parse(text);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function safeYaml(text) {
+    if (!text.trim())
+        return undefined;
+    try {
+        const parsed = parseYaml(text);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : undefined;
+    }
+    catch {
+        // Configuration files with custom tags or template syntax still identify
+        // the generator; only their values become unavailable.
+        return undefined;
+    }
+}
+/** The first `key: 'value'` or `key = "value"` pair in a JavaScript, Python, or TOML file. */
+function quotedValue(text, key) {
+    const match = new RegExp(`(?:^|[\\s{,])${key}\\s*[:=]\\s*(['"])([^'"\\n]+)\\1`, 'm').exec(text);
+    return match?.[2]?.trim() || undefined;
+}
+function tomlOrYamlValue(text, key) {
+    const quoted = quotedValue(text, key);
+    if (quoted)
+        return quoted;
+    const bare = new RegExp(`^\\s*${key}\\s*[:=]\\s*([^\\s#"']+)\\s*$`, 'mi').exec(text);
+    return bare?.[1]?.trim() || undefined;
+}
+function isSafeContentDir(value) {
+    const trimmed = value.trim();
+    return trimmed !== '' && !trimmed.startsWith('/') && !/^[a-zA-Z]:/.test(trimmed) && !trimmed.split(/[\\/]/).includes('..');
+}
+function portable(path) {
+    return sep === '/' ? path : path.split(sep).join('/');
+}
+//# sourceMappingURL=project-detect.js.map

package/dist/project-import.d.ts

@@ -0,0 +1,54 @@
+import { type GeneratorDetection } from './project-detect.js';
+import type { AgentName, GeneratorName } from './types.js';
+export interface ExistingDocumentationInspection {
+    conversion?: 'mintlify';
+    root: string;
+    /** `.doxloop/project.json` already exists here; open it instead of importing. */
+    alreadyProject: boolean;
+    detection: GeneratorDetection;
+    generator?: GeneratorName;
+    contentDir?: string;
+    title: string;
+    markers: string[];
+    pageCount: number;
+    /** The first pages, project-relative, so the person can confirm the folder is the right one. */
+    pages: string[];
+    generatorInstalled: boolean;
+    generatorPackage?: string;
+}
+export interface ImportExistingDocumentationOptions {
+    directory: string;
+    generator?: GeneratorName;
+    contentDir?: string;
+    title?: string;
+    agent?: AgentName;
+}
+export interface ImportExistingDocumentationResult {
+    root: string;
+    title: string;
+    generator: GeneratorName;
+    contentDir: string;
+    pageCount: number;
+    skills: Array<{
+        path: string;
+        action: 'installed' | 'updated' | 'unchanged';
+    }>;
+    warnings: string[];
+}
+/**
+ * Read-only look at a folder: what generator it uses, where its pages are,
+ * and how many there are. Explicit choices override detection so the person
+ * can correct a wrong guess before anything is written.
+ */
+export declare function inspectExistingDocumentation(directory: string, overrides?: {
+    generator?: GeneratorName;
+    contentDir?: string;
+}): Promise<ExistingDocumentationInspection>;
+/**
+ * Adopt an existing documentation folder as a Doxloop project. Import writes
+ * only Doxloop's own files (`.doxloop/project.json`, an evidence map that
+ * marks every page as unverified, `.gitignore` entries, and the agent
+ * skills) and runs a read-only discovery pass. It never modifies a page.
+ */
+export declare function importExistingDocumentation(options: ImportExistingDocumentationOptions): Promise<ImportExistingDocumentationResult>;
+//# sourceMappingURL=project-import.d.ts.map

package/dist/project-import.js

@@ -0,0 +1,157 @@
+import { mkdir, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { installSkill } from './agents.js';
+import { mintlifyMarker } from './mintlify-detect.js';
+import { DoxloopError } from './errors.js';
+import { EVIDENCE_MAP_FILE, readEvidenceMap, writeEvidenceMap } from './evidence.js';
+import { ensureGitignoreEntries, pathExists, resolveContainedDirectory } from './fs.js';
+import { generatorCatalogEntry, generatorPackageName, loadGeneratorAdapter, resolveGeneratorPackage } from './generators.js';
+import { PROJECT_FILE, PROJECT_GITIGNORE_ENTRIES, defaultDocumentationBrief, defaultSyncConfig, loadPages, loadProject, relativePath, titleFromDirectory, } from './project.js';
+import { detectDocumentationGenerator, listDocumentationPageFiles } from './project-detect.js';
+import { discoverDocumentationSources } from './source-discovery.js';
+const INSPECTION_PAGE_SAMPLE = 25;
+/**
+ * Read-only look at a folder: what generator it uses, where its pages are,
+ * and how many there are. Explicit choices override detection so the person
+ * can correct a wrong guess before anything is written.
+ */
+export async function inspectExistingDocumentation(directory, overrides = {}) {
+    const root = await resolveImportDirectory(directory);
+    const mintlify = await mintlifyMarker(root);
+    const alreadyProject = await pathExists(join(root, PROJECT_FILE));
+    const detection = await detectDocumentationGenerator(root);
+    const detected = overrides.generator
+        ? detection.candidates.find((candidate) => candidate.generator === overrides.generator)
+        : detection.recommended;
+    const generator = overrides.generator ?? detected?.generator;
+    const contentDir = overrides.contentDir !== undefined
+        ? normalizeContentDir(overrides.contentDir)
+        : detected?.contentDir ?? (generator ? defaultContentDir(generator) : undefined);
+    const pages = generator && contentDir !== undefined ? await listDocumentationPageFiles(root, generator, contentDir) : [];
+    const generatorPackage = generator ? generatorPackageName(generator) : undefined;
+    return {
+        ...(mintlify ? { conversion: 'mintlify' } : {}),
+        root,
+        alreadyProject,
+        detection,
+        ...(generator ? { generator } : {}),
+        ...(contentDir !== undefined ? { contentDir } : {}),
+        title: detected?.title ?? titleFromDirectory(root),
+        markers: detected?.markers ?? [],
+        pageCount: pages.length,
+        pages: pages.slice(0, INSPECTION_PAGE_SAMPLE),
+        generatorInstalled: !generatorPackage || resolveGeneratorPackage(root, generatorPackage) !== undefined,
+        ...(generatorPackage ? { generatorPackage } : {}),
+    };
+}
+/**
+ * Adopt an existing documentation folder as a Doxloop project. Import writes
+ * only Doxloop's own files (`.doxloop/project.json`, an evidence map that
+ * marks every page as unverified, `.gitignore` entries, and the agent
+ * skills) and runs a read-only discovery pass. It never modifies a page.
+ */
+export async function importExistingDocumentation(options) {
+    const root = await resolveImportDirectory(options.directory);
+    if (await pathExists(join(root, PROJECT_FILE))) {
+        throw new DoxloopError(`${root} is already a Doxloop project. Open it instead of importing it.`, 2);
+    }
+    const inspection = await inspectExistingDocumentation(root, {
+        ...(options.generator ? { generator: options.generator } : {}),
+        ...(options.contentDir !== undefined ? { contentDir: options.contentDir } : {}),
+    });
+    if (inspection.conversion === 'mintlify')
+        throw new DoxloopError('Mintlify must be converted to a new Doxbrix project. Use Import existing documentation → Mintlify to Doxbrix in the control center.');
+    const generator = inspection.generator;
+    if (!generator) {
+        throw new DoxloopError(`Could not recognize the documentation generator in ${root}.\nChoose one explicitly with --generator, or start a new project instead.`, 2);
+    }
+    const contentDir = inspection.contentDir ?? defaultContentDir(generator);
+    if (contentDir === '' && generator !== 'doxbrix') {
+        throw new DoxloopError(`${generatorCatalogEntry(generator)?.displayName ?? generator} keeps its pages in a subdirectory. Choose the content directory explicitly.`, 2);
+    }
+    await resolveContainedDirectory(root, contentDir, 'Documentation content directory', { allowRoot: generator === 'doxbrix' });
+    const configuredPackage = generatorPackageName(generator);
+    if (configuredPackage && !resolveGeneratorPackage(root, configuredPackage)) {
+        throw new DoxloopError(`The ${generatorCatalogEntry(generator)?.displayName ?? generator} generator package is not installed.\nInstall it in the documentation folder with:\n  doxloop generator add ${generator} --cwd ${root}`, 2);
+    }
+    const adapter = generator === 'doxbrix' ? undefined : await loadGeneratorAdapter(root, generator, configuredPackage);
+    const title = options.title?.trim() || inspection.title;
+    const project = {
+        schemaVersion: 1,
+        title,
+        contentDir,
+        generator,
+        ...(configuredPackage ? { generatorPackage: configuredPackage } : {}),
+        sources: [],
+        designReferences: [],
+        documentation: defaultDocumentationBrief(),
+        sync: defaultSyncConfig(),
+    };
+    await mkdir(join(root, '.doxloop'), { recursive: true });
+    await writeFile(join(root, PROJECT_FILE), `${JSON.stringify(project, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
+    const loaded = await loadProject(root);
+    const warnings = [];
+    const pages = (await loadPages(root, loaded)).map((path) => relativePath(root, path));
+    await seedEvidenceMap(root, pages);
+    await ensureGitignoreEntries(root, [...PROJECT_GITIGNORE_ENTRIES, ...(adapter?.project.gitignore ?? [])]);
+    const skills = await installSkill({ root, ...(options.agent ? { agent: options.agent } : {}) });
+    try {
+        await discoverDocumentationSources(root);
+    }
+    catch (error) {
+        warnings.push(`Discovery could not run yet: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return { root, title, generator, contentDir, pageCount: pages.length, skills, warnings };
+}
+/**
+ * Every existing page starts as unverified: no source produced it, so the
+ * first update run has to attach evidence before drift detection can trust
+ * it. An evidence map that is already present is kept as it is.
+ */
+async function seedEvidenceMap(root, pages) {
+    if (await pathExists(join(root, EVIDENCE_MAP_FILE))) {
+        await readEvidenceMap(root);
+        return;
+    }
+    const map = { schemaVersion: 1, pages: {} };
+    for (const page of pages)
+        map.pages[page] = { sources: [], confidence: 'needs-human' };
+    await writeEvidenceMap(root, map);
+}
+async function resolveImportDirectory(directory) {
+    const root = resolve(directory);
+    let stats;
+    try {
+        stats = await stat(root);
+    }
+    catch {
+        throw new DoxloopError(`The documentation folder does not exist: ${root}`, 2);
+    }
+    if (!stats.isDirectory())
+        throw new DoxloopError(`The documentation folder is not a directory: ${root}`, 2);
+    if (root === resolve(homedir()) || dirname(root) === root) {
+        throw new DoxloopError('Choose the folder that holds the documentation site, not your home directory or the filesystem root.', 2);
+    }
+    return root;
+}
+function normalizeContentDir(value) {
+    return value.trim().replace(/\\/g, '/').replace(/^\.\/+/, '').replace(/^\/+|\/+$/g, '');
+}
+function defaultContentDir(generator) {
+    const defaults = {
+        doxbrix: '',
+        docusaurus: 'docs',
+        mkdocs: 'docs',
+        sphinx: 'docs',
+        hugo: 'content',
+        vitepress: 'docs',
+        markdoc: 'docs',
+        nextra: 'content',
+        starlight: 'src/content/docs',
+        jekyll: '_docs',
+        static: 'site',
+    };
+    return defaults[generator];
+}
+//# sourceMappingURL=project-import.js.map

package/dist/project-lock.d.ts

@@ -0,0 +1,6 @@
+import { DoxloopError } from './errors.js';
+export declare class ProjectBusyError extends DoxloopError {
+}
+/** Reentrant within one operation; exclusive across UI, CLI and scheduled processes. */
+export declare function withProjectLock<T>(root: string, name: string, work: () => Promise<T>, timeoutMs?: number): Promise<T>;
+//# sourceMappingURL=project-lock.d.ts.map

package/dist/project-lock.js

@@ -0,0 +1,96 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { DoxloopError } from './errors.js';
+const heldLocks = new AsyncLocalStorage();
+export class ProjectBusyError extends DoxloopError {
+}
+/** Reentrant within one operation; exclusive across UI, CLI and scheduled processes. */
+export async function withProjectLock(root, name, work, timeoutMs = 10_000) {
+    if (!/^[a-z-]+$/.test(name))
+        throw new Error('Invalid project lock name');
+    const directory = join(await realpath(root), '.doxloop', 'locks');
+    const path = join(directory, `${name}.lock`);
+    if (heldLocks.getStore()?.has(path))
+        return work();
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const token = randomUUID();
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+        try {
+            await mkdir(path, { mode: 0o700 });
+            try {
+                await writeFile(join(path, 'owner.json'), JSON.stringify({ pid: process.pid, token }), { mode: 0o600 });
+            }
+            catch (error) {
+                await rm(path, { recursive: true, force: true });
+                throw error;
+            }
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            let reaped = false;
+            if (await abandoned(path)) {
+                const claim = join(path, 'reaping');
+                let claimed = false;
+                try {
+                    await mkdir(claim);
+                    claimed = true;
+                    // Another owner may have acquired the path since our initial observation.
+                    if (await abandoned(path)) {
+                        const stale = `${path}.${token}.abandoned`;
+                        await rename(path, stale);
+                        await rm(stale, { recursive: true, force: true });
+                        claimed = false;
+                        reaped = true;
+                    }
+                }
+                catch (cause) {
+                    if (!['ENOENT', 'EEXIST'].includes(cause.code ?? ''))
+                        throw cause;
+                }
+                finally {
+                    if (claimed)
+                        await rm(claim, { recursive: true, force: true });
+                }
+            }
+            // A lock left by a dead process was just removed: take it now, even with no wait allowed.
+            if (reaped)
+                continue;
+            if (Date.now() >= deadline)
+                throw new ProjectBusyError(`Another ${name} operation is running for this project. Wait for it to finish and retry.`);
+            await delay(40);
+        }
+    }
+    try {
+        return await heldLocks.run(new Set([...(heldLocks.getStore() ?? []), path]), work);
+    }
+    finally {
+        const owner = await readFile(join(path, 'owner.json'), 'utf8').catch(() => '');
+        if (owner && JSON.parse(owner).token === token)
+            await rm(path, { recursive: true, force: true });
+    }
+}
+async function abandoned(path) {
+    try {
+        const owner = JSON.parse(await readFile(join(path, 'owner.json'), 'utf8'));
+        if (!Number.isInteger(owner.pid) || owner.pid <= 0)
+            return false;
+        try {
+            process.kill(owner.pid, 0);
+            return false;
+        }
+        catch (error) {
+            return error.code === 'ESRCH';
+        }
+    }
+    catch {
+        // A creator may not yet have written its owner record. Never steal a new lock.
+        return Date.now() - (await stat(path).catch(() => ({ mtimeMs: Date.now() }))).mtimeMs > 60_000;
+    }
+}
+//# sourceMappingURL=project-lock.js.map

package/dist/project-registry.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The user-level list of documentation projects the control center has
+ * opened. It lives outside every project so switching between two workspaces
+ * is one click, and it records only what is needed to show and reopen them.
+ */
+export interface RecentProject {
+    path: string;
+    title: string;
+    generator: string;
+    lastOpenedAt: string;
+    /** The project file is gone. The entry stays until forgotten so the person can see where it was. */
+    missing?: boolean;
+}
+export declare const MAX_RECENT_PROJECTS = 20;
+/** `DOXLOOP_HOME` overrides the location so tests and CI never touch a real home directory. */
+export declare function doxloopHomeDirectory(): string;
+export declare function projectRegistryPath(): string;
+export declare function listRecentProjects(): Promise<RecentProject[]>;
+export declare function rememberProject(entry: {
+    path: string;
+    title: string;
+    generator: string;
+}): Promise<RecentProject[]>;
+export declare function forgetProject(path: string): Promise<RecentProject[]>;
+//# sourceMappingURL=project-registry.d.ts.map

package/dist/project-registry.js

@@ -0,0 +1,79 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { pathExists } from './fs.js';
+import { PROJECT_FILE } from './project.js';
+export const MAX_RECENT_PROJECTS = 20;
+/** `DOXLOOP_HOME` overrides the location so tests and CI never touch a real home directory. */
+export function doxloopHomeDirectory() {
+    const override = process.env.DOXLOOP_HOME?.trim();
+    return override ? resolve(override) : join(homedir(), '.doxloop');
+}
+export function projectRegistryPath() {
+    return join(doxloopHomeDirectory(), 'projects.json');
+}
+export async function listRecentProjects() {
+    const entries = await readRegistry();
+    return Promise.all(entries.map(async (entry) => ((await pathExists(join(entry.path, PROJECT_FILE))) ? entry : { ...entry, missing: true })));
+}
+export async function rememberProject(entry) {
+    const path = resolve(entry.path);
+    const others = (await readRegistry()).filter((item) => item.path !== path);
+    const next = [
+        { path, title: entry.title, generator: entry.generator, lastOpenedAt: new Date().toISOString() },
+        ...others,
+    ].slice(0, MAX_RECENT_PROJECTS);
+    await writeRegistry(next);
+    return next;
+}
+export async function forgetProject(path) {
+    const target = resolve(path);
+    const next = (await readRegistry()).filter((item) => item.path !== target);
+    await writeRegistry(next);
+    return next;
+}
+async function readRegistry() {
+    let raw;
+    try {
+        raw = await readFile(projectRegistryPath(), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        // The registry is a convenience. A damaged file must never keep the
+        // control center from opening; it is rewritten on the next open.
+        return [];
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return [];
+    const record = parsed;
+    if (record.schemaVersion !== 1 || !Array.isArray(record.projects))
+        return [];
+    return record.projects
+        .filter(isRecentProject)
+        .map((entry) => ({ path: resolve(entry.path), title: entry.title, generator: entry.generator, lastOpenedAt: entry.lastOpenedAt }))
+        .sort((left, right) => right.lastOpenedAt.localeCompare(left.lastOpenedAt));
+}
+async function writeRegistry(projects) {
+    const path = projectRegistryPath();
+    await mkdir(doxloopHomeDirectory(), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.tmp`;
+    const payload = projects.map(({ missing: _missing, ...entry }) => entry);
+    await writeFile(temporary, `${JSON.stringify({ schemaVersion: 1, projects: payload }, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    await rename(temporary, path);
+}
+function isRecentProject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const entry = value;
+    return (typeof entry.path === 'string' && entry.path.trim() !== '' &&
+        typeof entry.title === 'string' &&
+        typeof entry.generator === 'string' && entry.generator.trim() !== '' &&
+        typeof entry.lastOpenedAt === 'string' && !Number.isNaN(Date.parse(entry.lastOpenedAt)));
+}
+//# sourceMappingURL=project-registry.js.map