@anydocs/core 1.0.0

package/dist/services/web-runtime-bridge.js

@@ -0,0 +1,330 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { access, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:net';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ValidationError } from "../errors/validation-error.js";
+const CORE_PACKAGE_ROOT = path.dirname(fileURLToPath(new URL('../index.ts', import.meta.url)));
+let webRuntimeQueue = Promise.resolve();
+const WEB_RUNTIME_LOCK_DIR = '.anydocs-web-runtime.lock';
+const WEB_RUNTIME_LOCK_TIMEOUT_MS = 5 * 60000;
+const WEB_RUNTIME_LOCK_POLL_MS = 250;
+function resolveWebPackageRoot() {
+    const cwd = process.cwd();
+    const candidates = [
+        cwd,
+        path.join(cwd, 'packages', 'web'),
+        path.join(path.resolve(CORE_PACKAGE_ROOT, '../../..'), 'packages', 'web'),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(path.join(candidate, 'scripts', 'gen-public-assets.mjs'))) {
+            return candidate;
+        }
+    }
+    return path.join(path.resolve(CORE_PACKAGE_ROOT, '../../..'), 'packages', 'web');
+}
+const BRIDGE_ENV_ALLOWLIST = new Set([
+    'CI',
+    'COLORTERM',
+    'FORCE_COLOR',
+    'HOME',
+    'LANG',
+    'LC_ALL',
+    'LC_CTYPE',
+    'LOGNAME',
+    'PATH',
+    'PNPM_HOME',
+    'SHELL',
+    'TERM',
+    'TMPDIR',
+    'USER',
+    'XDG_CACHE_HOME',
+    'XDG_CONFIG_HOME',
+]);
+function createRuntimeEnv(mode, options) {
+    const baseEnv = Object.fromEntries(Object.entries(process.env).filter(([key]) => BRIDGE_ENV_ALLOWLIST.has(key)));
+    return {
+        ...baseEnv,
+        NODE_ENV: mode === 'export' ? 'production' : 'development',
+        ANYDOCS_DOCS_RUNTIME: mode,
+        ANYDOCS_DOCS_PROJECT_ROOT: options.projectRoot,
+        ...(options.outputRoot ? { ANYDOCS_DOCS_OUTPUT_ROOT: options.outputRoot } : {}),
+        ANYDOCS_DISABLE_STUDIO: '1',
+    };
+}
+function formatBridgeFailure(command, exitCode, signal, stderr) {
+    const details = stderr.trim();
+    const suffix = details ? `\n${details}` : '';
+    return new Error(`${command} failed (exit=${exitCode ?? 'null'}, signal=${signal ?? 'null'}).${suffix}`);
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isNodeError(error) {
+    return typeof error === 'object' && error !== null && ('code' in error || 'message' in error);
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return isNodeError(error) && error.code === 'EPERM';
+    }
+}
+async function cleanupStaleFilesystemLock(lockDir) {
+    try {
+        const owner = JSON.parse(await readFile(path.join(lockDir, 'owner.json'), 'utf8'));
+        if (typeof owner.pid === 'number' && !isPidAlive(owner.pid)) {
+            await rm(lockDir, { recursive: true, force: true });
+        }
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT') {
+            return;
+        }
+        throw error;
+    }
+}
+async function resolveNodeExecutable() {
+    const override = process.env.ANYDOCS_NODE_BINARY?.trim();
+    if (override) {
+        if (!path.isAbsolute(override)) {
+            return override;
+        }
+        await access(override);
+        return override;
+    }
+    return 'node';
+}
+function appendOutputTail(current, chunk, maxChars) {
+    const next = current + chunk;
+    return next.length > maxChars ? next.slice(-maxChars) : next;
+}
+function collectChildOutput(child, maxChars = 32000) {
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.on('data', (chunk) => {
+        stdout = appendOutputTail(stdout, chunk.toString(), maxChars);
+    });
+    child.stderr?.on('data', (chunk) => {
+        stderr = appendOutputTail(stderr, chunk.toString(), maxChars);
+    });
+    return {
+        stdout: () => stdout,
+        stderr: () => stderr,
+    };
+}
+function shellEscapeArg(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+async function createBridgeChild(mode, args, options) {
+    const nodeExecutable = await resolveNodeExecutable();
+    const shell = process.env.SHELL || '/bin/zsh';
+    const webPackageRoot = resolveWebPackageRoot();
+    const webBridgeScript = path.join(webPackageRoot, 'scripts', 'gen-public-assets.mjs');
+    const command = ['exec', nodeExecutable, webBridgeScript, mode, ...args].map(shellEscapeArg).join(' ');
+    return spawn(shell, ['-lc', command], {
+        cwd: webPackageRoot,
+        env: createRuntimeEnv(mode, options),
+        stdio: options.stdio === 'inherit' ? 'inherit' : 'pipe',
+    });
+}
+function waitForChildExit(child) {
+    return new Promise((resolve) => {
+        child.once('exit', (exitCode, signal) => {
+            resolve({ exitCode, signal });
+        });
+    });
+}
+async function acquireFilesystemWebRuntimeLock() {
+    const lockDir = path.join(resolveWebPackageRoot(), WEB_RUNTIME_LOCK_DIR);
+    const ownerPath = path.join(lockDir, 'owner.json');
+    const deadline = Date.now() + WEB_RUNTIME_LOCK_TIMEOUT_MS;
+    while (true) {
+        try {
+            await mkdir(lockDir);
+            await writeFile(ownerPath, JSON.stringify({
+                pid: process.pid,
+                acquiredAt: new Date().toISOString(),
+            }), 'utf8');
+            let released = false;
+            return async () => {
+                if (released) {
+                    return;
+                }
+                released = true;
+                await rm(lockDir, { recursive: true, force: true });
+            };
+        }
+        catch (error) {
+            if (!isNodeError(error) || error.code !== 'EEXIST') {
+                throw error;
+            }
+            await cleanupStaleFilesystemLock(lockDir);
+            if (Date.now() >= deadline) {
+                throw new Error(`Timed out waiting for the shared web runtime lock at "${lockDir}".`);
+            }
+            await delay(WEB_RUNTIME_LOCK_POLL_MS);
+        }
+    }
+}
+async function acquireWebRuntimeLock() {
+    const previous = webRuntimeQueue;
+    let releaseProcessQueue;
+    webRuntimeQueue = new Promise((resolve) => {
+        releaseProcessQueue = resolve;
+    });
+    await previous;
+    const releaseFilesystemLock = await acquireFilesystemWebRuntimeLock();
+    let released = false;
+    return async () => {
+        if (released) {
+            return;
+        }
+        released = true;
+        try {
+            await releaseFilesystemLock();
+        }
+        finally {
+            releaseProcessQueue();
+        }
+    };
+}
+export async function exportDocsSite(options) {
+    const releaseLock = await acquireWebRuntimeLock();
+    try {
+        const child = await createBridgeChild('export', [], options);
+        const output = collectChildOutput(child);
+        if (!child.stdout || !child.stderr) {
+            const result = await waitForChildExit(child);
+            if (result.exitCode !== 0) {
+                throw formatBridgeFailure('Docs site export', result.exitCode, result.signal, '');
+            }
+            return;
+        }
+        const result = await waitForChildExit(child);
+        if (result.exitCode !== 0) {
+            const stderr = [output.stderr().trim(), output.stdout().trim()].filter(Boolean).join('\n');
+            throw formatBridgeFailure('Docs site export', result.exitCode, result.signal, stderr);
+        }
+    }
+    finally {
+        await releaseLock();
+    }
+}
+async function pickAvailablePort(host) {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once('error', reject);
+        server.listen(0, host, () => {
+            const address = server.address();
+            if (!address || typeof address === 'string') {
+                server.close(() => reject(new Error('Failed to resolve an available preview port.')));
+                return;
+            }
+            const { port } = address;
+            server.close((closeError) => {
+                if (closeError) {
+                    reject(closeError);
+                    return;
+                }
+                resolve(port);
+            });
+        });
+    });
+}
+async function waitForPreviewServerReady(child, url, timeoutMs) {
+    const startedAt = Date.now();
+    const output = collectChildOutput(child);
+    while (Date.now() - startedAt < timeoutMs) {
+        if (child.exitCode !== null) {
+            const stderr = [output.stderr().trim(), output.stdout().trim()].filter(Boolean).join('\n');
+            throw formatBridgeFailure('Docs preview server', child.exitCode, null, stderr);
+        }
+        try {
+            const response = await fetch(url, { redirect: 'manual' });
+            if (response.status >= 200 && response.status < 400) {
+                return;
+            }
+        }
+        catch {
+            // Keep polling until timeout or process exit.
+        }
+        await new Promise((resolve) => setTimeout(resolve, 150));
+    }
+    child.kill('SIGTERM');
+    await waitForChildExit(child);
+    throw new Error(`Timed out waiting for docs preview server to become ready at ${url}.`);
+}
+export async function startDocsPreviewServer(options) {
+    const releaseLock = await acquireWebRuntimeLock();
+    try {
+        const host = options.host ?? '127.0.0.1';
+        const port = options.port ?? (await pickAvailablePort(host));
+        const readyPath = options.readyPath ?? '/';
+        const startTimeoutMs = options.startTimeoutMs ?? 30000;
+        const child = await createBridgeChild('preview', ['--hostname', host, '--port', String(port)], options);
+        const url = `http://${host}:${port}`;
+        const readyUrl = new URL(readyPath, `${url}/`).toString();
+        const exitPromise = waitForChildExit(child).finally(() => releaseLock());
+        await waitForPreviewServerReady(child, readyUrl, startTimeoutMs);
+        return {
+            child,
+            host,
+            port,
+            url,
+            stop: async () => {
+                if (child.exitCode !== null) {
+                    await exitPromise;
+                    return;
+                }
+                child.kill('SIGTERM');
+                await exitPromise;
+            },
+            waitUntilExit: () => exitPromise,
+        };
+    }
+    catch (error) {
+        await releaseLock();
+        throw error;
+    }
+}
+function isSameOrDescendantPath(candidatePath, parentPath) {
+    const relativePath = path.relative(parentPath, candidatePath);
+    return relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath));
+}
+export function assertSafeArtifactRoot(paths) {
+    const normalizedArtifactRoot = path.resolve(paths.artifactRoot);
+    const normalizedRepoRoot = path.resolve(paths.repoRoot);
+    const normalizedProjectRoot = path.resolve(paths.projectRoot);
+    if (normalizedArtifactRoot === normalizedRepoRoot || normalizedArtifactRoot === normalizedProjectRoot) {
+        throw new ValidationError(`Refusing to export the docs site into "${normalizedArtifactRoot}" because that would overwrite the project workspace.`, {
+            entity: 'artifact-root',
+            rule: 'artifact-root-must-not-overwrite-project-workspace',
+            remediation: 'Use the default dist directory or pass --output to a dedicated build output directory.',
+            metadata: { artifactRoot: normalizedArtifactRoot, repoRoot: normalizedRepoRoot, projectRoot: normalizedProjectRoot },
+        });
+    }
+    const protectedRoots = [
+        path.resolve(paths.pagesRoot),
+        path.resolve(paths.navigationRoot),
+        path.resolve(paths.importsRoot),
+    ];
+    const conflictingRoot = protectedRoots.find((protectedRoot) => isSameOrDescendantPath(normalizedArtifactRoot, protectedRoot));
+    if (!conflictingRoot) {
+        return;
+    }
+    throw new ValidationError(`Refusing to export the docs site into "${normalizedArtifactRoot}" because it overlaps source content at "${conflictingRoot}".`, {
+        entity: 'artifact-root',
+        rule: 'artifact-root-must-not-overlap-source-content',
+        remediation: 'Write build output to a dedicated directory such as dist/ or another folder outside pages/, navigation/, and imports/.',
+        metadata: {
+            artifactRoot: normalizedArtifactRoot,
+            conflictingRoot,
+            repoRoot: normalizedRepoRoot,
+            projectRoot: normalizedProjectRoot,
+        },
+    });
+}

package/dist/services/workflow-compatibility-service.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowCompatibilityAssessment } from '../types/workflow-standard.ts';
+export declare function assessWorkflowForwardCompatibility(repoRoot: string, projectId?: string): Promise<WorkflowCompatibilityAssessment>;
+//# sourceMappingURL=workflow-compatibility-service.d.ts.map

package/dist/services/workflow-compatibility-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-compatibility-service.d.ts","sourceRoot":"","sources":["../../src/services/workflow-compatibility-service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,+BAA+B,CAAC;AAoBrF,wBAAsB,kCAAkC,CACtD,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,+BAA+B,CAAC,CAiE1C"}

package/dist/services/workflow-compatibility-service.js

@@ -0,0 +1,53 @@
+import { loadProjectContract } from "../fs/content-repository.js";
+import { createWorkflowStandardDefinition, readWorkflowStandardDefinition, } from "./workflow-standard-service.js";
+import { ValidationError } from "../errors/validation-error.js";
+function createWorkflowCompatibilityError(rule, remediation, metadata) {
+    return new ValidationError(`Workflow compatibility validation failed for rule "${rule}".`, {
+        entity: 'workflow-compatibility',
+        rule,
+        remediation,
+        metadata,
+    });
+}
+export async function assessWorkflowForwardCompatibility(repoRoot, projectId) {
+    const contractResult = await loadProjectContract(repoRoot, projectId);
+    if (!contractResult.ok) {
+        throw contractResult.error;
+    }
+    const contract = contractResult.value;
+    const persisted = await readWorkflowStandardDefinition(contract.paths.workflowFile);
+    const expected = createWorkflowStandardDefinition(contract);
+    if (persisted.standardId !== expected.standardId) {
+        throw createWorkflowCompatibilityError('workflow-standard-compatible-standard-id', 'Regenerate the workflow standard so it matches the canonical phase 1 standard id.', { expected: expected.standardId, received: persisted.standardId });
+    }
+    if (persisted.projectContractVersion !== expected.projectContractVersion) {
+        throw createWorkflowCompatibilityError('workflow-standard-compatible-project-contract-version', 'Regenerate the workflow standard so it matches the current project contract version.', { expected: expected.projectContractVersion, received: persisted.projectContractVersion });
+    }
+    const persistedRequiredFields = [
+        ...persisted.contentModel.projectConfigFields,
+        ...persisted.contentModel.pageRequiredFields,
+        ...persisted.contentModel.navigationRequiredFields,
+    ];
+    const expectedRequiredFields = [
+        ...expected.contentModel.projectConfigFields,
+        ...expected.contentModel.pageRequiredFields,
+        ...expected.contentModel.navigationRequiredFields,
+    ];
+    const missingRequiredField = expectedRequiredFields.find((field) => !persistedRequiredFields.includes(field));
+    if (missingRequiredField) {
+        throw createWorkflowCompatibilityError('workflow-standard-compatible-required-fields', 'Regenerate the workflow standard so it includes the canonical required content-model fields.', { missingRequiredField });
+    }
+    const missingStep = expected.orchestration.workflowSteps.find((step) => !persisted.orchestration.workflowSteps.includes(step));
+    if (missingStep) {
+        throw createWorkflowCompatibilityError('workflow-standard-compatible-workflow-steps', 'Regenerate the workflow standard so it preserves the canonical orchestration steps.', { missingStep });
+    }
+    return {
+        compatible: true,
+        standardId: persisted.standardId,
+        projectContractVersion: persisted.projectContractVersion,
+        reusableAcrossProjects: true,
+        futureCompatibleWithoutReinitialization: true,
+        externalAutomationReady: true,
+        validatedAt: new Date().toISOString(),
+    };
+}

package/dist/services/workflow-standard-service.d.ts

@@ -0,0 +1,9 @@
+import type { WorkflowStandardDefinition, WorkflowStandardExport } from '../types/workflow-standard.ts';
+import type { ProjectContract } from '../types/project.ts';
+export declare function validateWorkflowStandardDefinition(input: unknown): WorkflowStandardDefinition;
+export declare function readWorkflowStandardDefinition(workflowFile: string): Promise<WorkflowStandardDefinition>;
+export declare function assertWorkflowStandardMatchesContract(definition: WorkflowStandardDefinition, contract: ProjectContract): void;
+export declare function createWorkflowStandardDefinition(contract: ProjectContract): WorkflowStandardDefinition;
+export declare function renderWorkflowStandardGuide(definition: WorkflowStandardDefinition): string;
+export declare function exportWorkflowStandard(contract: ProjectContract): WorkflowStandardExport;
+//# sourceMappingURL=workflow-standard-service.d.ts.map

package/dist/services/workflow-standard-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-standard-service.d.ts","sourceRoot":"","sources":["../../src/services/workflow-standard-service.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,0BAA0B,EAC1B,sBAAsB,EAEvB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AA6K3D,wBAAgB,kCAAkC,CAAC,KAAK,EAAE,OAAO,GAAG,0BAA0B,CAgJ7F;AA8DD,wBAAsB,8BAA8B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAyB9G;AAED,wBAAgB,qCAAqC,CACnD,UAAU,EAAE,0BAA0B,EACtC,QAAQ,EAAE,eAAe,GACxB,IAAI,CA0BN;AAED,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,eAAe,GACxB,0BAA0B,CAkC5B;AAED,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,0BAA0B,GAAG,MAAM,CAwC1F;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,eAAe,GAAG,sBAAsB,CAOxF"}