@doxbrix/doxloop 0.1.5 → 0.2.0

package/dist/project.js

@@ -1,11 +1,21 @@
+import { documentationCollections } from './documentation-collections.js';
 import { access, mkdir, readFile, readdir, realpath, stat, writeFile, } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep, } from 'node:path';
 import matter from 'gray-matter';
 import { DoxloopError } from './errors.js';
-import { listFiles, pathExists, readJson, resolveContainedDirectory, } from './fs.js';
+import { listFiles, ensureGitignoreEntries, pathExists, readJson, resolveContainedDirectory, } from './fs.js';
 import { generatorCatalogEntry, generatorPackageName, loadGeneratorAdapter, } from './generators.js';
 import { PACKAGE_NAME, VERSION } from './version.js';
 export const PROJECT_FILE = join('.doxloop', 'project.json');
+export const ROOT_CONTENT_IGNORED_DIRECTORIES = new Set([
+    '.agents',
+    '.claude',
+    '.codex',
+    '.doxloop',
+    '.gemini',
+    '.git',
+    'node_modules',
+]);
 export function defaultDocumentationBrief() {
     return {
         locale: 'en-US',
@@ -15,8 +25,36 @@ export function defaultDocumentationBrief() {
         terminology: {},
         exclusions: [],
         accessibilityTarget: 'WCAG 2.2 AA',
+        preferredExamples: [],
     };
 }
+export function completeDocumentationBriefForCreate(brief) {
+    const primaryAudience = brief.primaryAudience || brief.audiences?.join(', ') || 'Developers';
+    const priorityOutcomes = brief.priorityOutcomes?.length
+        ? brief.priorityOutcomes
+        : ['Reach a first successful result'];
+    return { ...brief, primaryAudience, priorityOutcomes };
+}
+/**
+ * Lock files and snapshots never change reader-visible behavior. Test files are
+ * deliberately absent: the authoring workflow treats tests as evidence of
+ * supported behavior, so a changed test can legitimately change documentation.
+ */
+const DEFAULT_SYNC_IGNORE = [
+    'Cargo.lock',
+    'Gemfile.lock',
+    'composer.lock',
+    'go.sum',
+    'package-lock.json',
+    'pnpm-lock.yaml',
+    'poetry.lock',
+    'yarn.lock',
+    '**/__snapshots__/**',
+    '*.snap',
+];
+export function defaultSyncConfig() {
+    return { mode: 'check', on: [], watch: [], ignore: [...DEFAULT_SYNC_IGNORE] };
+}
 export async function findProjectRoot(start) {
     let current = resolve(start);
     while (true) {
@@ -36,7 +74,7 @@ export async function loadProject(root) {
     if (project.schemaVersion !== 1 ||
         typeof project.title !== 'string' ||
         typeof project.contentDir !== 'string' ||
-        !isSafeRelativeDirectory(project.contentDir) ||
+        !isSafeRelativeDirectory(project.contentDir, selectedGenerator === 'doxbrix') ||
         !Array.isArray(project.sources) ||
         (project.designReferences !== undefined &&
             !isDesignReferences(project.designReferences)) ||
@@ -53,10 +91,14 @@ export async function loadProject(root) {
         !isSourceBindings(project.sources) ||
         (project.defaultAgent !== undefined &&
             !['codex', 'claude', 'gemini'].includes(project.defaultAgent)) ||
+        (project.defaultModel !== undefined &&
+            (typeof project.defaultModel !== 'string' || project.defaultModel.trim() === '')) ||
         (project.documentation !== undefined &&
-            !isDocumentationBrief(project.documentation))) {
+            !isDocumentationBrief(project.documentation)) ||
+        (project.sync !== undefined && !isSyncConfig(project.sync))) {
         throw new DoxloopError(`${PROJECT_FILE} has an unsupported format.`);
     }
+    validateSourceScopes(project.sources);
     const generator = selectedGenerator;
     return {
         schemaVersion: 1,
@@ -67,13 +109,24 @@ export async function loadProject(root) {
             ? { generatorPackage: project.generatorPackage }
             : {}),
         ...(project.defaultAgent ? { defaultAgent: project.defaultAgent } : {}),
+        ...(project.defaultAgent && project.defaultModel ? { defaultModel: project.defaultModel } : {}),
         sources: project.sources,
         designReferences: project.designReferences ?? [],
         ...(project.application ? { application: project.application } : {}),
         ...(project.deployment ? { deployment: project.deployment } : {}),
         documentation: project.documentation ?? defaultDocumentationBrief(),
+        sync: { ...defaultSyncConfig(), ...(project.sync ?? {}) },
     };
 }
+/**
+ * The project's saved default model, but only for the agent it was chosen
+ * for: a Codex model ID must not be handed to Claude Code or Gemini.
+ */
+export function projectDefaultModel(project, agent) {
+    if (!agent || !project.defaultModel || agent !== project.defaultAgent)
+        return undefined;
+    return project.defaultModel;
+}
 export async function saveDefaultAgent(root, agent) {
     const path = join(root, PROJECT_FILE);
     const raw = await readJson(path);
@@ -83,7 +136,7 @@ export async function saveProjectSettings(root, changes) {
     const path = join(root, PROJECT_FILE);
     const raw = await readJson(path);
     const next = { ...raw, ...changes };
-    for (const key of ['defaultAgent', 'application', 'deployment']) {
+    for (const key of ['defaultAgent', 'defaultModel', 'application', 'deployment', 'sync']) {
         if (key in changes && changes[key] === undefined)
             delete next[key];
     }
@@ -97,7 +150,7 @@ export async function saveProjectSettings(root, changes) {
 }
 export async function siteConfigPath(root, project) {
     const loaded = project ?? (await loadProject(root));
-    const contentRoot = await resolveContainedDirectory(root, loaded.contentDir, 'Documentation content directory');
+    const contentRoot = await resolveContainedDirectory(root, loaded.contentDir, 'Documentation content directory', { allowRoot: loaded.generator === 'doxbrix' });
     const insideContent = join(contentRoot, 'docs.json');
     if (await pathExists(insideContent))
         return insideContent;
@@ -176,6 +229,39 @@ function isSpecLocation(location) {
 export function sourceKind(source) {
     return source.kind ?? 'directory';
 }
+/**
+ * `--docs name=url` or `--docs url`: an existing documentation website to crawl.
+ * The returned binding is not yet materialized; its `path` holds the URL until
+ * the crawl writes the snapshot and replaces it with the snapshot directory.
+ */
+export function parseDocsSite(raw) {
+    const equals = raw.indexOf('=');
+    const looksNamed = equals > 0 && !/^https?:/i.test(raw.slice(0, equals));
+    const name = looksNamed ? raw.slice(0, equals).trim() : 'docs';
+    const location = (looksNamed ? raw.slice(equals + 1) : raw).trim();
+    if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+        throw new DoxloopError(`Invalid source name "${name}".`, 2);
+    }
+    if (!isSpecUrl(location)) {
+        throw new DoxloopError(`Invalid documentation site "${raw}". Use the HTTP(S) address of the existing documentation, for example --docs https://docs.example.com or --docs legacy=https://docs.example.com/guide/.`, 2);
+    }
+    let url;
+    try {
+        url = new URL(location);
+    }
+    catch {
+        throw new DoxloopError(`Invalid documentation site URL "${location}".`, 2);
+    }
+    if (url.username || url.password) {
+        throw new DoxloopError(`Invalid documentation site URL "${location}". Remove embedded credentials.`, 2);
+    }
+    url.hash = '';
+    return { name, path: url.toString(), kind: 'docs-site' };
+}
+/** A `docs-site` binding whose snapshot has not been crawled yet: its path is still the URL. */
+export function isUnmaterializedDocsSite(source) {
+    return sourceKind(source) === 'docs-site' && isSpecUrl(source.path);
+}
 export async function resolveSeparateProjectLayout(options) {
     const sourceRoot = resolve(options.cwd, options.source);
     const projectRoot = resolve(options.cwd, options.output);
@@ -192,11 +278,17 @@ export async function resolveSeparateProjectLayout(options) {
     };
 }
 export async function validateProjectSourceBoundaries(projectRoot, sources) {
+    validateSourceScopes(sources);
     for (const source of sources) {
         if (sourceKind(source) === 'openapi') {
+            await (await import('./openapi.js')).loadOpenApiSource(projectRoot, source);
+            continue;
+        }
+        if (sourceKind(source) === 'docs-site') {
             if (isSpecUrl(source.path))
-                continue;
-            await assertSpecFile(resolve(projectRoot, source.path));
+                throw new DoxloopError(`Documentation site source "${source.name}" has not been crawled yet: ${source.path}`);
+            await (await import('./docs-site.js')).assertDocsSiteSnapshot(projectRoot, source);
+            await assertSeparateDirectories(resolve(projectRoot, source.path), projectRoot);
             continue;
         }
         const sourceRoot = resolve(projectRoot, source.path);
@@ -204,6 +296,24 @@ export async function validateProjectSourceBoundaries(projectRoot, sources) {
         await assertSeparateDirectories(sourceRoot, projectRoot);
     }
 }
+export function validateSourceScopes(sources) {
+    const prefixes = sources.flatMap((source) => source.scope?.routePrefix ? [{ source: source.name, prefix: normalizeScopePath(source.scope.routePrefix) }] : []);
+    for (let index = 0; index < prefixes.length; index += 1) {
+        for (let other = index + 1; other < prefixes.length; other += 1) {
+            const left = prefixes[index];
+            const right = prefixes[other];
+            if (left.prefix === right.prefix || left.prefix.startsWith(`${right.prefix}/`) || right.prefix.startsWith(`${left.prefix}/`)) {
+                throw new DoxloopError(`Source scopes for "${left.source}" and "${right.source}" overlap at "${left.prefix}" and "${right.prefix}". Give each source a distinct route prefix; use sharedPages for intentional shared pages.`);
+            }
+        }
+    }
+}
+function normalizeScopePath(value) {
+    const normalized = value.replace(/\\/g, '/').replace(/^\/+|\/+$/g, '');
+    if (!normalized || normalized.split('/').includes('..'))
+        throw new DoxloopError('Source route prefixes must be safe relative paths.');
+    return normalized;
+}
 export async function assertNewProjectDirectory(projectRoot) {
     if (!(await pathExists(projectRoot)))
         return;
@@ -301,7 +411,7 @@ export async function scaffoldProject(options) {
     const adapter = generator === 'doxbrix'
         ? undefined
         : await loadGeneratorAdapter(root, generator, configuredPackage);
-    const contentDir = adapter?.project.defaultContentDir ?? 'docs';
+    const contentDir = adapter?.project.defaultContentDir ?? '';
     await mkdir(join(root, '.doxloop'), { recursive: true });
     await mkdir(join(root, contentDir), { recursive: true });
     const project = {
@@ -313,6 +423,7 @@ export async function scaffoldProject(options) {
         sources: options.sources,
         designReferences: options.designReferences ?? [],
         documentation: defaultDocumentationBrief(),
+        sync: defaultSyncConfig(),
     };
     await writeJson(join(root, PROJECT_FILE), project);
     if (adapter) {
@@ -328,24 +439,70 @@ export async function scaffoldProject(options) {
         });
     }
     else {
-        await scaffoldDoxbrix(root, title);
+        await scaffoldDoxbrix(root, title, contentDir);
     }
     await mergeGitignore(root, [
-        '.doxloop/cache/',
-        '.doxloop/last-run.json',
+        ...PROJECT_GITIGNORE_ENTRIES,
         ...(adapter?.project.gitignore ?? []),
     ]);
     return root;
 }
+/**
+ * Machine-local Doxloop state that never belongs in version control. Shared by
+ * the scaffold and by importing an existing documentation folder.
+ */
+export const PROJECT_GITIGNORE_ENTRIES = [
+    '.doxloop/cache/',
+    '.doxloop/runs/',
+    '.doxloop/last-run.json',
+    '.doxloop/sync.log',
+    '.doxloop/sync.log.1',
+    '.doxloop/locks/',
+    '.doxloop/direct-edits/',
+    '.doxloop/monitor-budget.json',
+    '.doxloop/quality-reports/',
+    '.doxloop/quality-artifacts/',
+    '.doxloop/evaluations/',
+    '.doxloop/ui-jobs.json',
+    '.doxloop/ui-job-logs/',
+    '.doxloop/review-preferences.json',
+    '.doxloop/deliveries/',
+    '.doxloop/exports/',
+    '.doxloop/doxloop.db',
+    '.doxloop/doxloop.db-wal',
+    '.doxloop/doxloop.db-shm',
+    'build/',
+];
 export async function loadPages(root, project) {
-    const contentRoot = await resolveContainedDirectory(root, project.contentDir, 'Documentation content directory');
+    const contentRoot = await resolveContainedDirectory(root, project.contentDir, 'Documentation content directory', { allowRoot: project.generator === 'doxbrix' });
     await access(contentRoot);
-    const extensions = project.generator === 'doxbrix'
-        ? ['.md', '.mdx']
-        : (await loadGeneratorAdapter(root, project)).project.pageExtensions;
-    return listFiles(contentRoot, new Set(extensions));
+    const extensions = await pageExtensions(root, project);
+    const collections = await documentationCollections(root, project);
+    const sets = await Promise.all(collections.map(async (collection) => {
+        const directory = await resolveContainedDirectory(root, collection.directory, 'Collection directory', { allowRoot: project.generator === 'doxbrix' });
+        return listFiles(directory, extensions, { ...(directory === resolve(root) ? { ignoredDirectories: ROOT_CONTENT_IGNORED_DIRECTORIES } : {}) });
+    }));
+    return [...new Set(sets.flat())].sort();
+}
+/**
+ * File extensions the configured generator treats as readable pages. Everything
+ * else inside the content directory is site data, not documentation.
+ */
+export async function pageExtensions(root, project) {
+    if (project.generator === 'doxbrix')
+        return new Set(['.md', '.mdx']);
+    try {
+        return new Set((await loadGeneratorAdapter(root, project)).project.pageExtensions);
+    }
+    catch {
+        // A generator package that cannot be loaded should not turn every data file
+        // into a reviewable page.
+        return new Set(['.md', '.mdx']);
+    }
 }
-function isSafeRelativeDirectory(value) {
+function isSafeRelativeDirectory(value, allowRoot = false) {
+    if (value === '')
+        return allowRoot;
     if (value.trim() === '' || isAbsolute(value))
         return false;
     const normalized = normalize(value);
@@ -357,9 +514,15 @@ export async function readPage(path) {
     const parsed = matter(await readFile(path, 'utf8'));
     const title = typeof parsed.data.title === 'string' ? parsed.data.title.trim() : '';
     const description = typeof parsed.data.description === 'string' ? parsed.data.description.trim() : undefined;
-    return description === undefined
-        ? { title, body: parsed.content }
-        : { title, description, body: parsed.content };
+    const canonical = typeof parsed.data.canonical === 'string' ? parsed.data.canonical.trim() : '';
+    const socialImage = typeof parsed.data.socialImage === 'string' ? parsed.data.socialImage.trim() : '';
+    return {
+        title,
+        ...(description === undefined ? {} : { description }),
+        body: parsed.content,
+        ...(canonical ? { canonical } : {}),
+        ...(socialImage ? { socialImage } : {}),
+    };
 }
 export function pageId(contentRoot, path) {
     return relativePath(contentRoot, path).replace(/\.[^.\/]+$/i, '');
@@ -371,26 +534,17 @@ async function writeJson(path, value) {
     await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
 }
 async function mergeGitignore(root, entries) {
-    const path = join(root, '.gitignore');
-    const existing = (await pathExists(path)) ? await readFile(path, 'utf8') : '';
-    const lines = existing.split(/\r?\n/).filter(Boolean);
-    const seen = new Set(lines);
-    for (const entry of entries) {
-        if (!seen.has(entry)) {
-            lines.push(entry);
-            seen.add(entry);
-        }
-    }
-    await writeFile(path, `${lines.join('\n')}\n`, 'utf8');
+    await ensureGitignoreEntries(root, entries);
 }
-function titleFromDirectory(directory) {
+export function titleFromDirectory(directory) {
     return basename(directory)
         .split(/[-_]+/)
         .filter(Boolean)
         .map((word) => `${word[0]?.toUpperCase() ?? ''}${word.slice(1)}`)
         .join(' ');
 }
-async function scaffoldDoxbrix(root, title) {
+async function scaffoldDoxbrix(root, title, contentDir) {
+    const contentRoot = contentDir ? join(root, contentDir) : root;
     const site = {
         version: 1,
         name: title,
@@ -431,9 +585,9 @@ async function scaffoldDoxbrix(root, title) {
             codeFont: 'ui-monospace',
         },
     };
-    await writeJson(join(root, 'docs', 'docs.json'), site);
-    await writeFile(join(root, 'docs', 'index.mdx'), `---\ntitle: ${JSON.stringify(title)}\ndescription: "Understand what ${title} helps you accomplish and choose your first workflow."\nicon: compass\n---\n\n# ${title}\n\n<!-- doxloop:starter-page -->\n\n<Info>The authoring agent will replace this starter with an evidence-backed product overview.</Info>\n\n<CardGroup cols="2">\n<Card title="Quickstart" icon="🚀" href="/quickstart">Reach your first successful result.</Card>\n<Card title="Explore the product" icon="🧭">Discover the workflows supported by the configured source.</Card>\n</CardGroup>\n`, { encoding: 'utf8', flag: 'wx' });
-    await writeFile(join(root, 'docs', 'quickstart.mdx'), `---\ntitle: "Quickstart"\ndescription: "Reach your first successful result with verified product instructions."\nicon: bolt\n---\n\n# Quickstart\n\n<!-- doxloop:starter-page -->\n\n<Steps>\n<Step title="Confirm the prerequisites">Use the authoring agent to identify supported requirements from source.</Step>\n<Step title="Complete the first workflow">Replace this starter with commands or code verified against the product.</Step>\n<Step title="Verify success">Show the observable result a reader should expect.</Step>\n</Steps>\n`, { encoding: 'utf8', flag: 'wx' });
+    await writeJson(join(contentRoot, 'docs.json'), site);
+    await writeFile(join(contentRoot, 'index.mdx'), `---\ntitle: ${JSON.stringify(title)}\ndescription: "Understand what ${title} helps you accomplish and choose your first workflow."\nicon: compass\n---\n\n# ${title}\n\n<!-- doxloop:starter-page -->\n\n<Info>The authoring agent will replace this starter with an evidence-backed product overview.</Info>\n\n<CardGroup cols="2">\n<Card title="Quickstart" icon="🚀" href="/quickstart">Reach your first successful result.</Card>\n<Card title="Explore the product" icon="🧭">Discover the workflows supported by the configured source.</Card>\n</CardGroup>\n`, { encoding: 'utf8', flag: 'wx' });
+    await writeFile(join(contentRoot, 'quickstart.mdx'), `---\ntitle: "Quickstart"\ndescription: "Reach your first successful result with verified product instructions."\nicon: bolt\n---\n\n# Quickstart\n\n<!-- doxloop:starter-page -->\n\n<Steps>\n<Step title="Confirm the prerequisites">Use the authoring agent to identify supported requirements from source.</Step>\n<Step title="Complete the first workflow">Replace this starter with commands or code verified against the product.</Step>\n<Step title="Verify success">Show the observable result a reader should expect.</Step>\n</Steps>\n`, { encoding: 'utf8', flag: 'wx' });
 }
 function isDoxbrixSiteConfig(value) {
     return doxbrixSiteConfigProblem(value) === undefined;
@@ -454,6 +608,29 @@ function doxbrixSiteConfigProblem(value) {
     }
     if (!Array.isArray(candidate.spaces))
         return 'spaces must be an array.';
+    if (candidate.versions !== undefined) {
+        if (!Array.isArray(candidate.versions))
+            return 'versions must be an array.';
+        const slugs = new Set();
+        for (const entry of candidate.versions) {
+            if (!entry || typeof entry !== 'object' || Array.isArray(entry) || typeof entry.version !== 'string' || !entry.version.trim())
+                return 'Each documentation version needs a non-empty version string.';
+            if (slugs.has(entry.version))
+                return `Duplicate documentation version "${entry.version}".`;
+            slugs.add(entry.version);
+            for (const key of ['label', 'tag'])
+                if (entry[key] !== undefined && typeof entry[key] !== 'string')
+                    return `Documentation version ${key} must be a string.`;
+            for (const key of ['default', 'isDefault'])
+                if (entry[key] !== undefined && typeof entry[key] !== 'boolean')
+                    return `Documentation version ${key} must be a boolean.`;
+        }
+        if (candidate.versions.length)
+            for (const space of candidate.spaces) {
+                if (space && typeof space === 'object' && typeof space.version === 'string' && !slugs.has(space.version))
+                    return `Space references unknown documentation version "${space.version}".`;
+            }
+    }
     for (const [spaceIndex, value] of candidate.spaces.entries()) {
         const location = `spaces[${spaceIndex}]`;
         if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -465,7 +642,7 @@ function doxbrixSiteConfigProblem(value) {
         }
         if (!Array.isArray(space.nav))
             return `${location}.nav must be an array.`;
-        const optionalStrings = ['slug', 'locale', 'parent', 'icon', 'tag'];
+        const optionalStrings = ['slug', 'locale', 'parent', 'icon', 'tag', 'version'];
         for (const key of optionalStrings) {
             if (space[key] !== undefined && typeof space[key] !== 'string') {
                 return `${location}.${key} must be a string.`;
@@ -571,7 +748,70 @@ function isSourceBindings(value) {
             typeof source.path === 'string' &&
             (source.kind === undefined ||
                 source.kind === 'directory' ||
-                source.kind === 'openapi')));
+                source.kind === 'openapi' ||
+                source.kind === 'docs-site') &&
+            isDocsSiteInfo(source.site) &&
+            isSourceScope(source.scope) &&
+            isRemoteSource(source.remote)));
+}
+function isDocsSiteInfo(value) {
+    if (value === undefined)
+        return true;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const site = value;
+    return typeof site.url === 'string' && typeof site.crawledAt === 'string' && typeof site.pages === 'number' && typeof site.hash === 'string';
+}
+function isSourceScope(value) {
+    if (value === undefined)
+        return true;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const scope = value;
+    const optionalText = (item) => item === undefined || (typeof item === 'string' && item.trim() !== '');
+    return optionalText(scope.space) && optionalText(scope.routePrefix) && optionalText(scope.navigationGroup) &&
+        (scope.sharedPages === undefined || (Array.isArray(scope.sharedPages) && scope.sharedPages.every((item) => typeof item === 'string' && item.trim() !== '')));
+}
+function isRemoteSource(value) {
+    if (value === undefined)
+        return true;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const remote = value;
+    if (remote.provider !== 'github' && remote.provider !== 'git')
+        return false;
+    if (typeof remote.repository !== 'string' ||
+        remote.repository.trim() === '' ||
+        typeof remote.branch !== 'string' ||
+        remote.branch.trim() === '')
+        return false;
+    if (remote.provider === 'github' && !/^[^/\s]+\/[^/\s]+$/.test(remote.repository))
+        return false;
+    if (remote.provider === 'git' &&
+        !/^(?:(?:https?|ssh|git|file):\/\/|[^@\s]+@[^:\s]+:)[^\r\n\0]+$/.test(remote.repository))
+        return false;
+    if (remote.tokenEnv !== undefined &&
+        (typeof remote.tokenEnv !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(remote.tokenEnv)))
+        return false;
+    if (remote.subdirectory !== undefined &&
+        (typeof remote.subdirectory !== 'string' ||
+            remote.subdirectory.trim() === '' ||
+            remote.subdirectory.startsWith('/') ||
+            remote.subdirectory.split(/[\\/]/).includes('..')))
+        return false;
+    if (remote.apiBaseUrl !== undefined) {
+        if (typeof remote.apiBaseUrl !== 'string')
+            return false;
+        try {
+            const url = new URL(remote.apiBaseUrl);
+            if (url.protocol !== 'https:' || url.username || url.password)
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
 }
 function isDesignReferences(value) {
     return (Array.isArray(value) &&
@@ -616,6 +856,14 @@ function isApplicationConfig(value, sources) {
             application.readyPath.startsWith('//'))) {
         return false;
     }
+    const authentication = application.authentication;
+    if (authentication !== undefined) {
+        if (!authentication || typeof authentication !== 'object' || Array.isArray(authentication))
+            return false;
+        if (authentication.loginPath !== undefined &&
+            (typeof authentication.loginPath !== 'string' || !validApplicationPath(authentication.loginPath)))
+            return false;
+    }
     const screenshots = application.screenshots;
     if (screenshots === undefined)
         return true;
@@ -627,6 +875,12 @@ function isApplicationConfig(value, sources) {
     if (screenshots.highlight !== undefined && typeof screenshots.highlight !== 'boolean') {
         return false;
     }
+    if (screenshots.startPath !== undefined &&
+        (typeof screenshots.startPath !== 'string' || !validApplicationPath(screenshots.startPath)))
+        return false;
+    if (screenshots.workflow !== undefined &&
+        (typeof screenshots.workflow !== 'string' || screenshots.workflow.trim().length < 12))
+        return false;
     if (screenshots.viewport === undefined)
         return true;
     return (Number.isInteger(screenshots.viewport.width) &&
@@ -636,6 +890,17 @@ function isApplicationConfig(value, sources) {
         screenshots.viewport.height >= 320 &&
         screenshots.viewport.height <= 2160);
 }
+function validApplicationPath(value) {
+    if (!value.startsWith('/') || value.startsWith('//'))
+        return false;
+    try {
+        const parsed = new URL(value, 'https://application.invalid');
+        return parsed.origin === 'https://application.invalid' && !parsed.hash;
+    }
+    catch {
+        return false;
+    }
+}
 function isDeploymentConfig(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return false;
@@ -644,6 +909,12 @@ function isDeploymentConfig(value) {
         (typeof candidate === 'string' && candidate.trim() !== '');
     if (!optionalText(deployment.name) || !optionalText(deployment.slug))
         return false;
+    if (deployment.target !== undefined && !['doxbrix', 'github-pages', 'netlify', 'vercel'].includes(deployment.target))
+        return false;
+    if (![deployment.siteId, deployment.projectId, deployment.teamId, deployment.branch, deployment.basePath].every(optionalText))
+        return false;
+    if (deployment.basePath?.split('/').some((part) => part === '..'))
+        return false;
     if (deployment.visibility !== undefined &&
         !['private', 'public'].includes(deployment.visibility)) {
         return false;
@@ -677,6 +948,81 @@ function isApplicationBaseUrl(value) {
         return false;
     }
 }
+export function parseSyncTrigger(raw) {
+    const value = raw.trim().toLowerCase();
+    const interval = /^every@(\d+)([mh])$/.exec(value);
+    if (interval) {
+        const amount = Number(interval[1]);
+        if ((interval[2] === 'm' && amount >= 1 && amount <= 59) ||
+            (interval[2] === 'h' && amount >= 1 && amount <= 24))
+            return value;
+    }
+    const daily = /^daily@(\d{2}):(\d{2})$/.exec(value);
+    if (daily) {
+        const hour = Number(daily[1]);
+        const minute = Number(daily[2]);
+        if (hour <= 23 && minute <= 59)
+            return value;
+    }
+    const weekdays = /^weekdays@(\d{2}):(\d{2})$/.exec(value);
+    if (weekdays && Number(weekdays[1]) <= 23 && Number(weekdays[2]) <= 59) {
+        return value;
+    }
+    const weekly = /^weekly@(sun|mon|tue|wed|thu|fri|sat)@(\d{2}):(\d{2})$/.exec(value);
+    if (weekly && Number(weekly[2]) <= 23 && Number(weekly[3]) <= 59) {
+        return value;
+    }
+    const monthly = /^monthly@(\d{1,2})@(\d{2}):(\d{2})$/.exec(value);
+    if (monthly && Number(monthly[1]) >= 1 && Number(monthly[1]) <= 28 && Number(monthly[2]) <= 23 && Number(monthly[3]) <= 59) {
+        return value;
+    }
+    throw new DoxloopError(`Invalid sync trigger "${raw}". Use daily, weekdays, weekly, monthly, or every interval syntax.`, 2);
+}
+function isSyncTrigger(value) {
+    if (typeof value !== 'string')
+        return false;
+    try {
+        parseSyncTrigger(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isSyncConfig(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const sync = value;
+    if (sync.mode !== undefined && !['check', 'propose', 'auto'].includes(sync.mode)) {
+        return false;
+    }
+    if (sync.branch !== undefined &&
+        (typeof sync.branch !== 'string' || sync.branch.trim() === '')) {
+        return false;
+    }
+    if (sync.on !== undefined && (!Array.isArray(sync.on) || !sync.on.every(isSyncTrigger))) {
+        return false;
+    }
+    const patternList = (candidate) => candidate === undefined ||
+        (Array.isArray(candidate) &&
+            candidate.every((item) => typeof item === 'string' && item.trim() !== ''));
+    if (!patternList(sync.watch) || !patternList(sync.ignore))
+        return false;
+    if (sync.maxVerificationAgeDays !== undefined && (!Number.isInteger(sync.maxVerificationAgeDays) || sync.maxVerificationAgeDays < 1 || sync.maxVerificationAgeDays > 3650))
+        return false;
+    if (sync.maxVerificationAgeSeverity !== undefined && !['warn', 'fail'].includes(sync.maxVerificationAgeSeverity))
+        return false;
+    if (sync.budget === undefined)
+        return true;
+    if (!sync.budget || typeof sync.budget !== 'object' || Array.isArray(sync.budget)) {
+        return false;
+    }
+    const limit = (candidate, max) => candidate === undefined ||
+        (Number.isInteger(candidate) && candidate >= 1 && candidate <= max);
+    const amount = (candidate, max) => candidate === undefined ||
+        (typeof candidate === 'number' && Number.isFinite(candidate) && candidate > 0 && candidate <= max);
+    return (limit(sync.budget.maxRunsPerDay, 1000) && limit(sync.budget.maxMinutes, 24 * 60) && amount(sync.budget.maxUsd, 100_000));
+}
 function isDocumentationBrief(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return false;
@@ -692,10 +1038,14 @@ function isDocumentationBrief(value) {
             typeof preferred === 'string' &&
             preferred.trim() !== '');
     return (optionalText(brief.primaryAudience) &&
+        (brief.audiences === undefined || textList(brief.audiences)) &&
+        optionalText(brief.customInstructions) &&
         (brief.experienceLevel === undefined ||
             ['beginner', 'intermediate', 'advanced', 'mixed'].includes(brief.experienceLevel)) &&
         (brief.priorityOutcomes === undefined ||
             textList(brief.priorityOutcomes)) &&
+        (brief.preferredExamples === undefined || textList(brief.preferredExamples)) &&
+        optionalText(brief.designDirection) &&
         typeof brief.locale === 'string' &&
         brief.locale.trim() !== '' &&
         textList(brief.tone) &&

package/dist/prompts.d.ts

@@ -27,6 +27,15 @@ export declare function promptText(options: {
     validate?: (value: string) => string | undefined | Promise<string | undefined>;
     io?: PromptIo;
 }): Promise<string>;
+/**
+ * Read one line without echoing it, for passwords. The readline interface
+ * writes its echo to a sink, so a terminal shows nothing while typing; piped
+ * input is read as a plain line.
+ */
+export declare function promptSecret(options: {
+    message: string;
+    io?: PromptIo;
+}): Promise<string>;
 export declare function promptConfirm(options: {
     message: string;
     initial?: boolean;