@anydocs/core 1.0.0

package/dist/services/preview-service.d.ts

@@ -0,0 +1,29 @@
+import type { DocsLanguage } from '../types/project.ts';
+export type PreviewWorkflowOptions = {
+    repoRoot: string;
+    projectId?: string;
+    host?: string;
+    port?: number;
+    startTimeoutMs?: number;
+    stdio?: 'pipe' | 'inherit';
+};
+export type PreviewTarget = {
+    projectId: string;
+    language: DocsLanguage;
+    docsPath: string;
+    publishedPages: number;
+};
+export type PreviewWorkflowResult = PreviewTarget & {
+    host: string;
+    port: number;
+    url: string;
+    pid: number;
+    stop: () => Promise<void>;
+    waitUntilExit: () => Promise<{
+        exitCode: number | null;
+        signal: NodeJS.Signals | null;
+    }>;
+};
+export declare function resolvePreviewTarget(options: PreviewWorkflowOptions): Promise<PreviewTarget>;
+export declare function runPreviewWorkflow(options: PreviewWorkflowOptions): Promise<PreviewWorkflowResult>;
+//# sourceMappingURL=preview-service.d.ts.map

package/dist/services/preview-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-service.d.ts","sourceRoot":"","sources":["../../src/services/preview-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,aAAa,GAAG;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,aAAa,EAAE,MAAM,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CAC1F,CAAC;AAEF,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,aAAa,CAAC,CAkBlG;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA2BxG"}

package/dist/services/preview-service.js

@@ -0,0 +1,45 @@
+import { loadProjectContract } from "../fs/content-repository.js";
+import { loadPublishedSiteBuildArtifacts } from "./build-service.js";
+export async function resolvePreviewTarget(options) {
+    const contractResult = await loadProjectContract(options.repoRoot, options.projectId);
+    if (!contractResult.ok) {
+        throw contractResult.error;
+    }
+    const contract = contractResult.value;
+    const language = contract.config.defaultLanguage;
+    const siteArtifacts = await loadPublishedSiteBuildArtifacts(options);
+    const defaultLanguageSite = siteArtifacts.find((entry) => entry.lang === language);
+    const firstPublishedRoute = defaultLanguageSite?.content.routes[0] ?? null;
+    return {
+        projectId: contract.config.projectId,
+        language,
+        docsPath: firstPublishedRoute?.href ?? `/${language}`,
+        publishedPages: defaultLanguageSite?.content.pages.length ?? 0,
+    };
+}
+export async function runPreviewWorkflow(options) {
+    const target = await resolvePreviewTarget(options);
+    const contractResult = await loadProjectContract(options.repoRoot, options.projectId);
+    if (!contractResult.ok) {
+        throw contractResult.error;
+    }
+    const contract = contractResult.value;
+    const { startDocsPreviewServer } = await import("./web-runtime-bridge.js");
+    const server = await startDocsPreviewServer({
+        projectRoot: contract.paths.projectRoot,
+        host: options.host,
+        port: options.port,
+        readyPath: target.docsPath,
+        startTimeoutMs: options.startTimeoutMs,
+        stdio: options.stdio,
+    });
+    return {
+        ...target,
+        host: server.host,
+        port: server.port,
+        url: server.url,
+        pid: server.child.pid ?? -1,
+        stop: server.stop,
+        waitUntilExit: server.waitUntilExit,
+    };
+}

package/dist/services/watch-service.d.ts

@@ -0,0 +1,24 @@
+export type ProjectWatchOptions = {
+    repoRoot: string;
+    projectId?: string;
+};
+export type ProjectWatchTrigger = {
+    eventType: string;
+    targetPath: string;
+    filename?: string;
+};
+export type ProjectWatchRunContext = {
+    reason: 'initial' | 'change';
+    runNumber: number;
+    trigger?: ProjectWatchTrigger;
+};
+export type ProjectWatchLoopOptions<TResult> = ProjectWatchOptions & {
+    debounceMs?: number;
+    execute: (options: ProjectWatchOptions) => Promise<TResult>;
+    signal: AbortSignal;
+    onSuccess?: (result: TResult, context: ProjectWatchRunContext) => void | Promise<void>;
+    onError?: (error: unknown, context: ProjectWatchRunContext) => void | Promise<void>;
+};
+export declare function resolveProjectWatchTargets(options: ProjectWatchOptions): Promise<string[]>;
+export declare function runProjectWatchLoop<TResult>(options: ProjectWatchLoopOptions<TResult>): Promise<void>;
+//# sourceMappingURL=watch-service.d.ts.map

package/dist/services/watch-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-service.d.ts","sourceRoot":"","sources":["../../src/services/watch-service.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,mBAAmB,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,uBAAuB,CAAC,OAAO,IAAI,mBAAmB,GAAG;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5D,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,sBAAsB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,sBAAsB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrF,CAAC;AAsJF,wBAAsB,0BAA0B,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAgBhG;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,uBAAuB,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CA0G3G"}

package/dist/services/watch-service.js

@@ -0,0 +1,216 @@
+import { readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { createDefaultProjectConfig } from "../config/project-config.js";
+import { loadProjectContract } from "../fs/content-repository.js";
+const DEFAULT_DEBOUNCE_MS = 100;
+const DEFAULT_POLL_INTERVAL_MS = 250;
+function normalizeTarget(targetPath) {
+    return path.resolve(targetPath);
+}
+function isMissingPathError(error) {
+    return !!error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT';
+}
+function shouldIgnoreSnapshotEntry(entryName) {
+    return entryName.endsWith('.tmp');
+}
+async function waitForDelay(signal, delayMs) {
+    if (signal.aborted) {
+        return false;
+    }
+    await new Promise((resolve) => {
+        const timeout = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, delayMs);
+        const onAbort = () => {
+            clearTimeout(timeout);
+            resolve();
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+    return !signal.aborted;
+}
+async function captureDirectorySnapshot(rootPath, currentPath = rootPath) {
+    let directoryEntries;
+    try {
+        directoryEntries = await readdir(currentPath, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isMissingPathError(error)) {
+            return [];
+        }
+        throw error;
+    }
+    directoryEntries.sort((left, right) => left.name.localeCompare(right.name));
+    const snapshotEntries = [];
+    for (const entry of directoryEntries) {
+        if (shouldIgnoreSnapshotEntry(entry.name)) {
+            continue;
+        }
+        const absolutePath = path.join(currentPath, entry.name);
+        const relativePath = path.relative(rootPath, absolutePath) || entry.name;
+        let entryStats;
+        try {
+            entryStats = await stat(absolutePath);
+        }
+        catch (error) {
+            if (isMissingPathError(error)) {
+                continue;
+            }
+            throw error;
+        }
+        if (entryStats.isDirectory()) {
+            snapshotEntries.push(`dir:${relativePath}`);
+            snapshotEntries.push(...(await captureDirectorySnapshot(rootPath, absolutePath)));
+            continue;
+        }
+        snapshotEntries.push(`file:${relativePath}:${entryStats.mtimeMs}:${entryStats.size}`);
+    }
+    return snapshotEntries;
+}
+async function captureTargetSnapshot(targetPath) {
+    let targetStats;
+    try {
+        targetStats = await stat(targetPath);
+    }
+    catch (error) {
+        if (isMissingPathError(error)) {
+            return 'missing';
+        }
+        throw error;
+    }
+    if (!targetStats.isDirectory()) {
+        return `file:${targetStats.mtimeMs}:${targetStats.size}`;
+    }
+    const entries = await captureDirectorySnapshot(targetPath);
+    return `dir:${entries.join('|')}`;
+}
+async function captureProjectSnapshot(targets) {
+    const snapshotEntries = await Promise.all(targets.map(async (targetPath) => [targetPath, await captureTargetSnapshot(targetPath)]));
+    return new Map(snapshotEntries);
+}
+function findChangedTarget(previousState, nextState) {
+    for (const [targetPath, previousSnapshot] of previousState.snapshot.entries()) {
+        if (nextState.snapshot.get(targetPath) !== previousSnapshot) {
+            return targetPath;
+        }
+    }
+    for (const targetPath of nextState.snapshot.keys()) {
+        if (!previousState.snapshot.has(targetPath)) {
+            return targetPath;
+        }
+    }
+    return null;
+}
+async function captureProjectWatchState(targets) {
+    return {
+        targets,
+        snapshot: await captureProjectSnapshot(targets),
+    };
+}
+async function resolveProjectWatchState(options) {
+    return captureProjectWatchState(await resolveProjectWatchTargets(options));
+}
+export async function resolveProjectWatchTargets(options) {
+    const projectId = options.projectId ?? createDefaultProjectConfig().projectId;
+    const contractResult = await loadProjectContract(options.repoRoot, projectId);
+    if (!contractResult.ok) {
+        throw contractResult.error;
+    }
+    const contract = contractResult.value;
+    const targets = new Set([
+        contract.paths.configFile,
+        contract.paths.workflowFile,
+        contract.paths.pagesRoot,
+        contract.paths.navigationRoot,
+    ]);
+    return [...targets].map(normalizeTarget).sort();
+}
+export async function runProjectWatchLoop(options) {
+    const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    let currentState = await resolveProjectWatchState(options);
+    let runNumber = 0;
+    const refreshState = async () => {
+        try {
+            return await resolveProjectWatchState(options);
+        }
+        catch (error) {
+            // Keep polling the last known-good canonical targets so edits can recover the project.
+            if (currentState.targets.length === 0) {
+                throw error;
+            }
+            return captureProjectWatchState(currentState.targets);
+        }
+    };
+    const executeRun = async (reason, observedState, trigger) => {
+        runNumber += 1;
+        const context = { reason, runNumber, ...(trigger ? { trigger } : {}) };
+        const result = await options.execute({
+            repoRoot: options.repoRoot,
+            ...(options.projectId ? { projectId: options.projectId } : {}),
+        });
+        const nextState = await refreshState();
+        const queuedTarget = findChangedTarget(observedState, nextState);
+        currentState = nextState;
+        await options.onSuccess?.(result, context);
+        return queuedTarget
+            ? {
+                eventType: 'change',
+                targetPath: queuedTarget,
+            }
+            : null;
+    };
+    const handleRunError = async (error, observedState, trigger) => {
+        await options.onError?.(error, {
+            reason: 'change',
+            runNumber: runNumber + 1,
+            trigger,
+        });
+        const nextState = await refreshState();
+        const queuedTarget = findChangedTarget(observedState, nextState);
+        currentState = nextState;
+        return queuedTarget
+            ? {
+                eventType: 'change',
+                targetPath: queuedTarget,
+            }
+            : null;
+    };
+    let queuedTrigger = await executeRun('initial', currentState);
+    while (!options.signal.aborted) {
+        if (queuedTrigger) {
+            const trigger = queuedTrigger;
+            queuedTrigger = null;
+            const observedState = currentState;
+            try {
+                queuedTrigger = await executeRun('change', observedState, trigger);
+            }
+            catch (error) {
+                queuedTrigger = await handleRunError(error, observedState, trigger);
+            }
+            continue;
+        }
+        const shouldContinue = await waitForDelay(options.signal, Math.max(DEFAULT_POLL_INTERVAL_MS, debounceMs));
+        if (!shouldContinue) {
+            break;
+        }
+        const nextState = await refreshState();
+        const changedTarget = findChangedTarget(currentState, nextState);
+        currentState = nextState;
+        if (!changedTarget) {
+            continue;
+        }
+        try {
+            queuedTrigger = await executeRun('change', currentState, {
+                eventType: 'change',
+                targetPath: changedTarget,
+            });
+        }
+        catch (error) {
+            queuedTrigger = await handleRunError(error, currentState, {
+                eventType: 'change',
+                targetPath: changedTarget,
+            });
+        }
+    }
+}

package/dist/services/web-runtime-bridge.d.ts

@@ -0,0 +1,33 @@
+import { type ChildProcess } from 'node:child_process';
+import type { ProjectPathContract } from '../types/project.ts';
+export type DocsRuntimeMode = 'export' | 'preview';
+type BaseBridgeOptions = {
+    projectRoot: string;
+    outputRoot?: string;
+    stdio?: 'pipe' | 'inherit';
+};
+export type ExportDocsSiteOptions = BaseBridgeOptions & {
+    outputRoot: string;
+};
+export type StartDocsPreviewServerOptions = BaseBridgeOptions & {
+    host?: string;
+    port?: number;
+    readyPath?: string;
+    startTimeoutMs?: number;
+};
+export type DocsPreviewServerProcess = {
+    child: ChildProcess;
+    host: string;
+    port: number;
+    url: string;
+    stop: () => Promise<void>;
+    waitUntilExit: () => Promise<{
+        exitCode: number | null;
+        signal: NodeJS.Signals | null;
+    }>;
+};
+export declare function exportDocsSite(options: ExportDocsSiteOptions): Promise<void>;
+export declare function startDocsPreviewServer(options: StartDocsPreviewServerOptions): Promise<DocsPreviewServerProcess>;
+export declare function assertSafeArtifactRoot(paths: ProjectPathContract): void;
+export {};
+//# sourceMappingURL=web-runtime-bridge.d.ts.map

package/dist/services/web-runtime-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-runtime-bridge.d.ts","sourceRoot":"","sources":["../../src/services/web-runtime-bridge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAQ9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AA4C/D,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEnD,KAAK,iBAAiB,GAAG;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,GAAG;IACtD,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG,iBAAiB,GAAG;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,aAAa,EAAE,MAAM,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CAC1F,CAAC;AA0LF,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBlF;AAyDD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,wBAAwB,CAAC,CAuCnC;AAOD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CA6CvE"}