@aopslabs/aops 0.3.22 → 0.3.24

package/dist/commands/doc.js

@@ -13,6 +13,7 @@ import { probeCliRuntimeMode } from '../utils/api.js';
 import { parseFrontmatterDocument } from '../utils/memory-workspace.js';
 const DEFAULT_DOC_BUILD_TIMEOUT_MS = 120_000;
 const DOC_MIRROR_CONTRACT = 'doc-mirror-v2';
+export const DOC_SOURCE_MIRROR_CONTRACT = 'doc-mirror-v3';
 function collectRepeatedOption(value, previous = []) {
     const normalized = normalizeNonEmpty(value);
     return normalized ? [...previous, normalized] : previous;
@@ -288,6 +289,210 @@ function materializedContent(result) {
 function sha256Hex(content) {
     return createHash('sha256').update(content).digest('hex');
 }
+function sha256ContentHash(content) {
+    return `sha256:${sha256Hex(content)}`;
+}
+export function validateSourceFileExtension(value, label = 'file extension') {
+    const extension = normalizeNonEmpty(value);
+    if (!extension || !/^[a-z0-9][a-z0-9_-]{0,31}$/.test(extension)) {
+        throw new Error(`${label} must be explicit lowercase ASCII without a leading dot (for example: cs, txt, or py).`);
+    }
+    return extension;
+}
+export function resolveDocMirrorVersionProfile(version, documentVersionId = '<unknown>') {
+    const rawContentMode = normalizeNonEmpty(version.contentMode)?.toLowerCase();
+    if (rawContentMode && rawContentMode !== 'structured' && rawContentMode !== 'text-file') {
+        throw new Error(`Docman version ${documentVersionId} has unsupported contentMode ${rawContentMode}.`);
+    }
+    const contentMode = rawContentMode === 'text-file' ? 'text-file' : 'structured';
+    const persistedExtension = normalizeNonEmpty(version.fileExtension);
+    if (contentMode === 'text-file') {
+        return {
+            contentMode,
+            fileExtension: validateSourceFileExtension(persistedExtension, `Document version ${documentVersionId} fileExtension`),
+        };
+    }
+    const fileExtension = persistedExtension
+        ? validateSourceFileExtension(persistedExtension, `Document version ${documentVersionId} fileExtension`)
+        : 'md';
+    if (fileExtension !== 'md') {
+        throw new Error(`Structured Docman version ${documentVersionId} declares persisted fileExtension ${fileExtension}; ` +
+            'doc-mirror-v2 only supports md until an explicit structured mirror path migration contract exists.');
+    }
+    return { contentMode, fileExtension };
+}
+export function decodeSourceFileBuffer(buffer, sourcePath = '<source>') {
+    if (buffer.includes(0)) {
+        throw new Error(`Source file ${sourcePath} contains a binary NUL byte; text-file push stopped.`);
+    }
+    try {
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(buffer);
+    }
+    catch {
+        throw new Error(`Source file ${sourcePath} is not valid UTF-8; text-file push stopped.`);
+    }
+}
+async function readUtf8SourceFile(sourceInput) {
+    const source = normalizeNonEmpty(sourceInput);
+    if (!source)
+        throw new Error('Provide --source or --source-file.');
+    if (source === '-') {
+        throw new Error('Text-file source must be a filesystem path; stdin cannot provide an extension-safe mirror identity.');
+    }
+    const absolutePath = path.resolve(source.startsWith('@') ? source.slice(1) : source);
+    const buffer = await readFile(absolutePath);
+    const content = decodeSourceFileBuffer(buffer, absolutePath);
+    return { absolutePath, content, contentHash: sha256ContentHash(content) };
+}
+function requireSha256ContentHash(value, label) {
+    const contentHash = normalizeNonEmpty(value);
+    if (!contentHash || !/^sha256:[a-f0-9]{64}$/.test(contentHash)) {
+        throw new Error(`${label} must use sha256:<64 lowercase hex characters>.`);
+    }
+    return contentHash;
+}
+export function parseDocSourceMirrorSidecar(value, sidecarPath = '<sidecar>') {
+    if (!isRecord(value))
+        throw new Error(`Docman source sidecar ${sidecarPath} must contain a JSON object.`);
+    if (value.contract !== DOC_SOURCE_MIRROR_CONTRACT || value.schemaVersion !== 3) {
+        throw new Error(`Docman source sidecar ${sidecarPath} must use ${DOC_SOURCE_MIRROR_CONTRACT} schemaVersion 3.`);
+    }
+    if (value.entityType !== 'docman.document-source-mirror' ||
+        value.source !== 'docman' ||
+        value.readOnly !== false ||
+        value.contentMode !== 'text-file' ||
+        value.sourceFormat !== 'text') {
+        throw new Error(`Docman source sidecar ${sidecarPath} has an invalid v3 mirror identity.`);
+    }
+    const documentId = normalizeNonEmpty(value.documentId);
+    const documentVersionId = normalizeNonEmpty(value.documentVersionId);
+    const documentSlug = normalizeNonEmpty(value.documentSlug);
+    const title = normalizeNonEmpty(value.title);
+    const mediaType = normalizeNonEmpty(value.mediaType);
+    const mirrorPath = normalizeNonEmpty(value.mirrorPath);
+    const pulledAt = normalizeNonEmpty(value.pulledAt);
+    const documentVersion = Number(value.documentVersion);
+    if (!documentId || !documentVersionId || !documentSlug || !title || !mediaType || !mirrorPath || !pulledAt) {
+        throw new Error(`Docman source sidecar ${sidecarPath} is missing required mirror provenance.`);
+    }
+    if (!Number.isInteger(documentVersion) || documentVersion < 1) {
+        throw new Error(`Docman source sidecar ${sidecarPath} has an invalid documentVersion.`);
+    }
+    const fileExtension = validateSourceFileExtension(value.fileExtension, `Sidecar ${sidecarPath} fileExtension`);
+    const contentHash = requireSha256ContentHash(value.contentHash, `Sidecar ${sidecarPath} contentHash`);
+    return {
+        schemaVersion: 3,
+        entityType: 'docman.document-source-mirror',
+        contract: DOC_SOURCE_MIRROR_CONTRACT,
+        readOnly: false,
+        source: 'docman',
+        projectId: normalizeNonEmpty(value.projectId),
+        projectName: normalizeNonEmpty(value.projectName),
+        projectSlug: normalizeNonEmpty(value.projectSlug),
+        scopeId: normalizeNonEmpty(value.scopeId),
+        groupId: normalizeNonEmpty(value.groupId),
+        groupUid: normalizeNonEmpty(value.groupUid),
+        documentId,
+        documentVersionId,
+        documentVersion,
+        documentSlug,
+        title,
+        contentMode: 'text-file',
+        sourceFormat: 'text',
+        fileExtension,
+        mediaType,
+        contentHash,
+        mirrorPath,
+        pulledAt,
+    };
+}
+export async function readDocSourceMirrorSidecar(sidecarInput) {
+    const absolutePath = path.resolve(sidecarInput);
+    let content;
+    try {
+        content = await readFile(absolutePath, 'utf8');
+    }
+    catch (error) {
+        if (isFileSystemError(error, 'ENOENT')) {
+            throw new Error(`Docman source mirror sidecar is missing: ${absolutePath}. Push stopped.`);
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        throw new Error(`Docman source mirror sidecar is not valid JSON: ${absolutePath}.`);
+    }
+    return parseDocSourceMirrorSidecar(parsed, absolutePath);
+}
+function parseSourceMaterializedPayload(result, expectedVersionId) {
+    const payload = unwrapResultData(result);
+    const documentVersionId = normalizeNonEmpty(payload?.documentVersionId);
+    if (documentVersionId !== expectedVersionId) {
+        throw new Error(`Docman source materialize returned version ${documentVersionId ?? '<missing>'}; expected ${expectedVersionId}.`);
+    }
+    const content = payload?.content;
+    if (typeof content !== 'string')
+        throw new Error('Docman source materialize did not return textual content.');
+    if (payload?.contentMode !== 'text-file' || payload.sourceFormat !== 'text') {
+        throw new Error('Docman source materialize did not return a text-file/text payload.');
+    }
+    const fileExtension = validateSourceFileExtension(payload.fileExtension, 'Materialized fileExtension');
+    const contentHash = requireSha256ContentHash(payload.contentHash, 'Materialized contentHash');
+    if (contentHash !== sha256ContentHash(content)) {
+        throw new Error('Docman source materialize contentHash does not match the exact UTF-8 content.');
+    }
+    const mediaType = normalizeNonEmpty(payload.mediaType);
+    const suggestedFileName = normalizeNonEmpty(payload.suggestedFileName);
+    if (!mediaType || !suggestedFileName) {
+        throw new Error('Docman source materialize is missing mediaType or suggestedFileName.');
+    }
+    return {
+        documentVersionId,
+        content,
+        contentHash,
+        contentMode: 'text-file',
+        sourceFormat: 'text',
+        fileExtension,
+        mediaType,
+        suggestedFileName,
+    };
+}
+export function validateDocSourceMirrorPushBaseline(params) {
+    const filenameExtension = path.extname(params.sourcePath).slice(1);
+    if (filenameExtension !== params.sidecar.fileExtension) {
+        throw new Error(`Source filename extension ${filenameExtension || '<missing>'} does not match persisted sidecar extension ${params.sidecar.fileExtension}.`);
+    }
+    if (path.basename(params.sidecar.mirrorPath) !== path.basename(params.sourcePath)) {
+        throw new Error(`Source filename ${path.basename(params.sourcePath)} does not match sidecar mirrorPath ${params.sidecar.mirrorPath}.`);
+    }
+    if (params.sidecar.scopeId && params.resolvedScopeId && params.sidecar.scopeId !== params.resolvedScopeId) {
+        throw new Error(`Source sidecar scope ${params.sidecar.scopeId} does not match resolved scope ${params.resolvedScopeId}.`);
+    }
+    if (params.sidecar.projectId && params.resolvedProjectId && params.sidecar.projectId !== params.resolvedProjectId) {
+        throw new Error(`Source sidecar project ${params.sidecar.projectId} does not match resolved project ${params.resolvedProjectId}.`);
+    }
+    const currentVersionId = recordId(params.currentVersion, 'documentVersionId');
+    if (currentVersionId !== params.sidecar.documentVersionId) {
+        throw new Error(`Stale source sidecar version ${params.sidecar.documentVersionId}; hosted current version is ${currentVersionId ?? '<missing>'}.`);
+    }
+    if (normalizeNonEmpty(params.currentVersion.contentMode) !== 'text-file') {
+        throw new Error(`Hosted current version ${currentVersionId} is not a text-file document version.`);
+    }
+    const currentExtension = validateSourceFileExtension(params.currentVersion.fileExtension, `Hosted current version ${currentVersionId} fileExtension`);
+    if (currentExtension !== params.sidecar.fileExtension) {
+        throw new Error(`Stale source sidecar extension ${params.sidecar.fileExtension}; hosted current extension is ${currentExtension}.`);
+    }
+    if (params.hostedSource.fileExtension !== params.sidecar.fileExtension) {
+        throw new Error(`Stale source sidecar extension ${params.sidecar.fileExtension}; materialized extension is ${params.hostedSource.fileExtension}.`);
+    }
+    if (params.hostedSource.contentHash !== params.sidecar.contentHash) {
+        throw new Error(`Stale source sidecar hash ${params.sidecar.contentHash}; hosted current hash is ${params.hostedSource.contentHash}.`);
+    }
+    return params.sourceContentHash === params.sidecar.contentHash ? 'up-to-date' : 'create-version';
+}
 function pathSegmentSlug(value, fallback) {
     const normalized = normalizeNonEmpty(value) ?? fallback;
     const safe = normalized
@@ -1574,6 +1779,67 @@ function buildDocMirrorFile(params) {
         content: `${frontmatter}<!-- READ-ONLY MIRROR: update Docman/source docs, then run aops-cli doc mirror pull. -->\n\n${params.content}`,
     };
 }
+export function buildDocSourceMirrorArtifacts(params) {
+    const documentId = recordId(params.document, 'documentId');
+    const documentVersionId = recordId(params.documentVersion, 'documentVersionId');
+    const documentSlug = normalizeNonEmpty(params.document.slug) ??
+        pathSegmentSlug(normalizeNonEmpty(params.document.title), documentId ?? 'document');
+    const title = normalizeNonEmpty(params.document.title) ?? documentSlug;
+    const version = recordVersion(params.documentVersion);
+    if (!documentId || !documentVersionId || version < 1) {
+        throw new Error('Text-file mirror plan is missing document/version provenance.');
+    }
+    const fileExtension = validateSourceFileExtension(params.materialized.fileExtension);
+    if (params.materialized.contentHash !== sha256ContentHash(params.materialized.content)) {
+        throw new Error('Docman source mirror artifact contentHash does not match the exact raw UTF-8 content.');
+    }
+    if (!params.materialized.suggestedFileName.endsWith(`.${fileExtension}`)) {
+        throw new Error(`Docman suggested source filename ${params.materialized.suggestedFileName} conflicts with persisted extension ${fileExtension}.`);
+    }
+    const mirrorPath = path.join(params.groupPath, `${pathSegmentSlug(documentSlug, 'document')}.${fileExtension}`);
+    const rawPath = path.join(params.outputRoot, mirrorPath);
+    const sidecarPath = `${rawPath}.docman.json`;
+    const sidecar = {
+        schemaVersion: 3,
+        entityType: 'docman.document-source-mirror',
+        contract: DOC_SOURCE_MIRROR_CONTRACT,
+        readOnly: false,
+        source: 'docman',
+        projectId: params.resolvedContext.projectId,
+        projectName: params.resolvedContext.projectName,
+        projectSlug: params.resolvedContext.projectSlug,
+        scopeId: params.resolvedContext.scopeId,
+        groupId: normalizeNonEmpty(params.document.groupId),
+        groupUid: normalizeNonEmpty(params.document.groupUid),
+        documentId,
+        documentVersionId,
+        documentVersion: version,
+        documentSlug,
+        title,
+        contentMode: 'text-file',
+        sourceFormat: 'text',
+        fileExtension,
+        mediaType: params.materialized.mediaType,
+        contentHash: params.materialized.contentHash,
+        mirrorPath: mirrorPath.split(path.sep).join('/'),
+        pulledAt: new Date().toISOString(),
+    };
+    return {
+        raw: { filePath: rawPath, content: params.materialized.content },
+        sidecar: { filePath: sidecarPath, content: `${JSON.stringify(sidecar, null, 2)}\n` },
+        entry: {
+            title,
+            mirrorPath: sidecar.mirrorPath,
+            sidecarPath: path.relative(params.outputRoot, sidecarPath).split(path.sep).join('/'),
+            documentId,
+            documentVersionId,
+            documentVersion: version,
+            contentMode: 'text-file',
+            fileExtension,
+            contentHash: sidecar.contentHash,
+        },
+    };
+}
 function buildDocMirrorIndex(params) {
     const indexPath = path.join(params.outputRoot, 'index.md');
     const frontmatter = renderFrontmatter({
@@ -1591,7 +1857,7 @@ function buildDocMirrorIndex(params) {
         frontmatter,
         '# Docman Mirror Index',
         '',
-        'This directory is a read-only mirror of hosted Docman documents. Edit canonical Docman/source docs, then run `aops-cli doc mirror pull --apply`.',
+        'This directory mirrors hosted Docman documents. Structured v2 `.md` files are read-only; text-file v3 entries are editable only with their adjacent `.docman.json` sidecar and guarded `aops-cli doc mirror push --source-file <path>`.',
         '',
         ...params.entries.map((entry) => {
             const title = normalizeNonEmpty(entry.title) ?? 'Untitled';
@@ -1678,11 +1944,47 @@ export async function commitStagedMirrorFiles(files) {
 async function listDocMirrorIndexEntries(outputRoot) {
     const files = await listLocalMirrorMarkdownFiles(outputRoot);
     const docs = await readLocalMirrorDocumentsFromFiles(outputRoot, files);
-    return docs.map((doc) => ({
+    const structured = docs.map((doc) => ({
         title: doc.title,
         mirrorPath: doc.relativePath,
         documentVersion: doc.documentVersion,
     }));
+    return [...structured, ...(await listDocSourceMirrorIndexEntries(outputRoot))];
+}
+async function listDocSourceMirrorSidecarFiles(root) {
+    try {
+        const entries = await readdir(root, { withFileTypes: true });
+        const nested = await Promise.all(entries.map(async (entry) => {
+            const fullPath = path.join(root, entry.name);
+            if (entry.isDirectory() && !entry.name.startsWith('.'))
+                return listDocSourceMirrorSidecarFiles(fullPath);
+            if (entry.isFile() && entry.name.endsWith('.docman.json'))
+                return [fullPath];
+            return [];
+        }));
+        return nested.flat().sort();
+    }
+    catch {
+        return [];
+    }
+}
+async function listDocSourceMirrorIndexEntries(outputRoot) {
+    const entries = [];
+    for (const sidecarPath of await listDocSourceMirrorSidecarFiles(outputRoot)) {
+        const sidecar = await readDocSourceMirrorSidecar(sidecarPath);
+        entries.push({
+            title: sidecar.title,
+            mirrorPath: sidecar.mirrorPath,
+            sidecarPath: path.relative(outputRoot, sidecarPath).split(path.sep).join('/'),
+            documentId: sidecar.documentId,
+            documentVersionId: sidecar.documentVersionId,
+            documentVersion: sidecar.documentVersion,
+            contentMode: sidecar.contentMode,
+            fileExtension: sidecar.fileExtension,
+            contentHash: sidecar.contentHash,
+        });
+    }
+    return entries;
 }
 function localMirrorLimit(value) {
     const parsed = toInteger(value, '--limit');
@@ -1702,8 +2004,15 @@ async function listLocalMirrorMarkdownFiles(root) {
             const fullPath = path.join(root, entry.name);
             if (entry.isDirectory() && !entry.name.startsWith('.'))
                 return listLocalMirrorMarkdownFiles(fullPath);
-            if (entry.isFile() && entry.name.endsWith('.md') && entry.name.toLowerCase() !== 'index.md')
-                return [fullPath];
+            if (entry.isFile() && entry.name.endsWith('.md') && entry.name.toLowerCase() !== 'index.md') {
+                try {
+                    await stat(`${fullPath}.docman.json`);
+                    return [];
+                }
+                catch {
+                    return [fullPath];
+                }
+            }
             return [];
         }));
         return nested.flat().sort();
@@ -2320,12 +2629,172 @@ export async function runDocImportMarkdown(options = {}) {
         process.exitCode = 1;
     }
 }
+export async function runDocSourceFileSave(options = {}) {
+    try {
+        const documentId = normalizeNonEmpty(options.documentId);
+        if (!documentId)
+            throw new Error('Provide --document-id.');
+        const source = await readUtf8SourceFile(options.source);
+        const fileExtension = validateSourceFileExtension(options.extension, '--extension');
+        const expectedPreviousContentHash = options.expectedContentHash === undefined
+            ? undefined
+            : requireSha256ContentHash(options.expectedContentHash, '--expected-content-hash');
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveDocContext(options, apiState, { forceHostedScope: true });
+        const auditFields = await resolveDocAuditFields(apiState, options, {}, 'create');
+        const input = compactPayload({
+            documentId,
+            content: source.content,
+            fileExtension,
+            title: normalizeNonEmpty(options.title),
+            expectedPreviousVersionId: normalizeNonEmpty(options.expectedVersionId),
+            expectedPreviousContentHash,
+            publishNow: options.publishNow === true,
+            ...auditFields,
+        });
+        const previewInput = compactPayload({
+            ...input,
+            content: undefined,
+            sourcePath: source.absolutePath,
+            sourceContentHash: source.contentHash,
+            sourceBytes: Buffer.byteLength(source.content, 'utf8'),
+        });
+        if (await guardDocWrite({
+            options,
+            command: 'doc.source-file.save',
+            surface: 'docman.document.source-file.save',
+            resolvedContext,
+            input: previewInput,
+        }))
+            return;
+        const result = await invokeDocCrudMutationRaw(apiState, options, resolvedContext, 'docman.document.source-file.save', input, { idempotencyKey: normalizeNonEmpty(options.idempotencyKey) });
+        await emitDocResult({
+            options,
+            command: 'doc.source-file.save',
+            surface: 'docman.document.source-file.save',
+            resolvedContext,
+            input: previewInput,
+            result,
+            artifacts: compactPayload({
+                documentId,
+                documentVersionId: normalizeNonEmpty(unwrapCrudData(result).documentVersionId),
+                contentHash: normalizeNonEmpty(unwrapCrudData(result).contentHash),
+            }),
+            successText: options.publishNow === true
+                ? 'Docman source-file snapshot saved and published.'
+                : 'Docman source-file draft snapshot saved.',
+        });
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+async function runDocSourceMirrorPush(options, apiState, resolvedContext) {
+    const source = await readUtf8SourceFile(options.sourceFile);
+    const sidecarPath = path.resolve(normalizeNonEmpty(options.sidecar) ?? `${source.absolutePath}.docman.json`);
+    const sidecar = await readDocSourceMirrorSidecar(sidecarPath);
+    const versions = await listDocumentVersions(apiState, options, resolvedContext, sidecar.documentId);
+    const current = selectCurrentPublishedDocumentVersion(versions, sidecar.documentId);
+    const hostedMaterialized = await callDocmanVersionRoute(apiState, options, resolvedContext, {
+        documentVersionId: sidecar.documentVersionId,
+        suffix: 'materialize',
+        method: 'POST',
+        body: compactPayload({
+            documentVersionId: sidecar.documentVersionId,
+            target: 'source',
+            locale: normalizeNonEmpty(options.locale),
+            fallbackLocale: normalizeNonEmpty(options.fallbackLocale),
+        }),
+    });
+    const hostedSource = parseSourceMaterializedPayload(hostedMaterialized, sidecar.documentVersionId);
+    const action = validateDocSourceMirrorPushBaseline({
+        sourcePath: source.absolutePath,
+        sourceContentHash: source.contentHash,
+        sidecar,
+        currentVersion: current,
+        hostedSource,
+        resolvedScopeId: normalizeNonEmpty(resolvedContext.scopeId),
+        resolvedProjectId: normalizeNonEmpty(resolvedContext.projectId),
+    });
+    const auditFields = await resolveDocAuditFields(apiState, options, {}, 'create');
+    const saveInput = compactPayload({
+        documentId: sidecar.documentId,
+        content: source.content,
+        fileExtension: sidecar.fileExtension,
+        title: normalizeNonEmpty(options.title) ?? sidecar.title,
+        expectedPreviousVersionId: sidecar.documentVersionId,
+        expectedPreviousContentHash: sidecar.contentHash,
+        publishNow: options.publishNow === true,
+        ...auditFields,
+    });
+    const input = {
+        sourcePath: source.absolutePath,
+        sidecarPath,
+        action,
+        sourceContentHash: source.contentHash,
+        sourceBytes: Buffer.byteLength(source.content, 'utf8'),
+        documentId: sidecar.documentId,
+        expectedPreviousVersionId: sidecar.documentVersionId,
+        expectedPreviousContentHash: sidecar.contentHash,
+        fileExtension: sidecar.fileExtension,
+        publishNow: options.publishNow === true,
+    };
+    if (await guardDocWrite({
+        options,
+        command: 'doc.mirror.push',
+        surface: `${DOC_SOURCE_MIRROR_CONTRACT} guarded source push`,
+        resolvedContext,
+        input,
+    }))
+        return;
+    if (action === 'up-to-date') {
+        await emitDocResult({
+            options,
+            command: 'doc.mirror.push',
+            surface: `${DOC_SOURCE_MIRROR_CONTRACT} guarded source push`,
+            resolvedContext,
+            input,
+            result: { action, changed: false, documentId: sidecar.documentId, documentVersionId: sidecar.documentVersionId },
+            successText: 'Docman source mirror is already up to date.',
+        });
+        return;
+    }
+    const result = await invokeDocCrudMutationRaw(apiState, options, resolvedContext, 'docman.document.source-file.save', saveInput, { idempotencyKey: normalizeNonEmpty(options.idempotencyKey) });
+    await emitDocResult({
+        options,
+        command: 'doc.mirror.push',
+        surface: `${DOC_SOURCE_MIRROR_CONTRACT} guarded source push`,
+        resolvedContext,
+        input,
+        result,
+        artifacts: compactPayload({
+            sourcePath: source.absolutePath,
+            sidecarPath,
+            documentId: sidecar.documentId,
+            documentVersionId: normalizeNonEmpty(unwrapCrudData(result).documentVersionId),
+            contentHash: normalizeNonEmpty(unwrapCrudData(result).contentHash),
+        }),
+        successText: options.publishNow === true
+            ? 'Docman source mirror snapshot pushed and published.'
+            : 'Docman source mirror draft snapshot pushed; run pull only after publishing it current.',
+    });
+}
 export async function runDocMirrorPush(options = {}) {
     try {
         const apiState = await requireApiState(options);
         if (!apiState)
             return;
         const resolvedContext = await resolveDocContext(options, apiState, { forceHostedScope: true });
+        if (normalizeNonEmpty(options.sourceFile)) {
+            await runDocSourceMirrorPush(options, apiState, resolvedContext);
+            return;
+        }
+        if (normalizeNonEmpty(options.sidecar)) {
+            throw new Error('--sidecar requires --source-file.');
+        }
         const groupUid = normalizeNonEmpty(options.groupUid) ?? 'architecture';
         const groupTitle = normalizeNonEmpty(options.groupTitle) ?? 'Architecture';
         const sources = await readRootMarkdownSources(options.sourceDir);
@@ -2581,7 +3050,11 @@ export async function runDocMirrorPull(options = {}) {
             const groupPath = buildGroupPath(document, groupsById, groupsByUid);
             const documentSlug = normalizeNonEmpty(document.slug) ??
                 pathSegmentSlug(normalizeNonEmpty(document.title), normalizeNonEmpty(documentId) ?? 'document');
-            const mirrorPath = path.join(groupPath, `${pathSegmentSlug(documentSlug, 'document')}.md`);
+            const profile = resolveDocMirrorVersionProfile(latest, documentVersionId);
+            const { contentMode } = profile;
+            const fileExtension = contentMode === 'text-file' ? profile.fileExtension : undefined;
+            const materializeTarget = contentMode === 'text-file' ? 'source' : target;
+            const mirrorPath = path.join(groupPath, `${pathSegmentSlug(documentSlug, 'document')}.${fileExtension ?? 'md'}`);
             const canonicalMirrorPath = path.resolve(outputRoot, mirrorPath).toLowerCase();
             if (seenMirrorPaths.has(canonicalMirrorPath)) {
                 throw new Error(`Docman mirror plan contains duplicate output path ${mirrorPath}.`);
@@ -2595,6 +3068,9 @@ export async function runDocMirrorPull(options = {}) {
                 slug: documentSlug,
                 groupPath,
                 mirrorPath,
+                contentMode,
+                fileExtension,
+                target: materializeTarget,
             });
         }
         const input = compactPayload({
@@ -2623,14 +3099,23 @@ export async function runDocMirrorPull(options = {}) {
             const document = documents.find((entry) => recordId(entry, 'documentId') === documentId);
             if (!document)
                 throw new Error(`Validated mirror plan references unknown document ${documentId}.`);
-            const documentVersion = { id: documentVersionId, documentId, version: plan.documentVersion, status: 'published', isCurrent: true };
+            const documentVersion = {
+                id: documentVersionId,
+                documentId,
+                version: plan.documentVersion,
+                status: 'published',
+                isCurrent: true,
+                contentMode: plan.contentMode,
+                fileExtension: plan.fileExtension,
+            };
+            const materializeTarget = normalizeNonEmpty(plan.target) ?? target;
             const materialized = await callDocmanVersionRoute(apiState, options, resolvedContext, {
                 documentVersionId,
                 suffix: 'materialize',
                 method: 'POST',
                 body: compactPayload({
                     documentVersionId,
-                    target,
+                    target: materializeTarget,
                     locale: normalizeNonEmpty(options.locale),
                     fallbackLocale: normalizeNonEmpty(options.fallbackLocale),
                 }),
@@ -2641,27 +3126,54 @@ export async function runDocMirrorPull(options = {}) {
                 throw new Error(`Docman materialize returned version ${returnedVersionId ?? '<missing>'}; expected ${documentVersionId}. ` +
                     'Mirror pull stopped before replacing any destination file.');
             }
-            const content = materializedContent(materialized);
-            materializedPlans.push({ plan, document, documentVersion, content });
+            if (plan.contentMode === 'text-file') {
+                const source = parseSourceMaterializedPayload(materialized, documentVersionId);
+                if (source.fileExtension !== plan.fileExtension) {
+                    throw new Error(`Docman source materialize extension ${source.fileExtension} differs from persisted version extension ${String(plan.fileExtension)}.`);
+                }
+            }
+            else {
+                materializedContent(materialized);
+            }
+            materializedPlans.push({ plan, document, documentVersion, materialized });
         }
         const existingIndexEntries = await listDocMirrorIndexEntries(outputRoot);
         const written = [];
-        const artifacts = materializedPlans.map(({ plan, document, documentVersion, content }) => {
-            const artifact = buildDocMirrorFile({
-                outputRoot,
-                groupPath: normalizeNonEmpty(plan.groupPath) ?? 'ungrouped',
-                document,
-                documentVersion,
-                resolvedContext,
-                target,
-                content,
-            });
-            written.push({
-                ...plan,
-                outputPath: artifact.filePath,
-            });
-            return artifact;
-        });
+        const artifacts = [];
+        for (const { plan, document, documentVersion, materialized } of materializedPlans) {
+            if (plan.contentMode === 'text-file') {
+                const sourceArtifacts = buildDocSourceMirrorArtifacts({
+                    outputRoot,
+                    groupPath: normalizeNonEmpty(plan.groupPath) ?? 'ungrouped',
+                    document,
+                    documentVersion,
+                    resolvedContext,
+                    materialized: parseSourceMaterializedPayload(materialized, normalizeNonEmpty(plan.documentVersionId) ?? ''),
+                });
+                artifacts.push(sourceArtifacts.raw, sourceArtifacts.sidecar);
+                written.push({
+                    ...plan,
+                    ...sourceArtifacts.entry,
+                    outputPath: sourceArtifacts.raw.filePath,
+                });
+            }
+            else {
+                const artifact = buildDocMirrorFile({
+                    outputRoot,
+                    groupPath: normalizeNonEmpty(plan.groupPath) ?? 'ungrouped',
+                    document,
+                    documentVersion,
+                    resolvedContext,
+                    target: normalizeNonEmpty(plan.target) ?? target,
+                    content: materializedContent(materialized),
+                });
+                artifacts.push(artifact);
+                written.push({
+                    ...plan,
+                    outputPath: artifact.filePath,
+                });
+            }
+        }
         const indexEntriesByPath = new Map();
         for (const entry of existingIndexEntries) {
             const mirrorPath = normalizeNonEmpty(entry.mirrorPath);
@@ -4758,8 +5270,8 @@ export async function runDocPublish(options = {}) {
         const resolvedContext = await resolveDocContext(options, apiState);
         const documentVersionId = requireDocumentVersionId(options);
         const target = normalizeNonEmpty(options.target) ?? 'markdown';
-        if (target !== 'markdown' && target !== 'html') {
-            throw new Error('Target must be markdown or html.');
+        if (target !== 'markdown' && target !== 'html' && target !== 'source') {
+            throw new Error('Target must be markdown, html, or source.');
         }
         const input = compactPayload({
             documentVersionId,
@@ -5305,11 +5817,28 @@ export function makeDocCommand() {
             'A dry-run returns a short-lived planToken. Pass it to --apply --plan-token <token> to reject source or graph drift; apply without a token remains supported.',
         ],
     }));
-    const mirror = cmd.command('mirror').description('Docman mirror pull and markdown import helpers');
+    const sourceFile = cmd.command('source-file').description('Immutable Docman text-file snapshot commands');
+    applyDocContextOptions(applyWriteOptions(sourceFile
+        .command('save')
+        .description('Save an exact UTF-8 source file as a new immutable text-file document version')
+        .requiredOption('--document-id <id>', 'Existing Docman document id')
+        .requiredOption('--source <path>', 'UTF-8 source file path')
+        .requiredOption('--extension <extension>', 'Explicit persisted lowercase extension without a leading dot')
+        .option('--title <title>', 'Snapshot/page title')
+        .option('--expected-version-id <id>', 'Reject unless this remains the previous current/latest version')
+        .option('--expected-content-hash <hash>', 'Reject unless previous source content still has this sha256 hash')
+        .option('--publish-now', 'Atomically publish/select the new snapshot as current')).action(async (options) => {
+        await runDocSourceFileSave(options);
+    }));
+    const mirror = cmd.command('mirror').description('Docman v2 structured and v3 source-file mirror helpers');
     applyDocContextOptions(applyWriteOptions(mirror
         .command('push')
-        .description('Import root markdown files into hosted Docman; use manual doc version/section/page commands for canonical graph authoring')
+        .description('Import root markdown files or guarded-push one v3 source file with its adjacent sidecar')
         .option('--source-dir <path>', 'Directory containing root *.md files', 'docs')
+        .option('--source-file <path>', 'V3 source file to guarded-push; requires adjacent <file>.docman.json')
+        .option('--sidecar <path>', 'Explicit v3 sidecar path (default: <source-file>.docman.json)')
+        .option('--title <title>', 'Optional title for the new v3 source snapshot')
+        .option('--publish-now', 'Atomically publish/select the pushed v3 snapshot as current')
         .option('--group-title <title>', 'Document group title to create/use')
         .option('--group-uid <uid>', 'Document group uid to create/use')
         .option('--document-status <value>', 'Document status: draft, published, archived', 'published')
@@ -5321,7 +5850,7 @@ export function makeDocCommand() {
     }));
     applyDocContextOptions(applyWriteOptions(mirror
         .command('pull')
-        .description('Materialize hosted Docman documents into .aops/docman read-only mirrors')
+        .description('Materialize structured v2 .md mirrors and exact v3 source files with adjacent sidecars')
         .option('--group-uid <uid>', 'Only pull one document group uid')
         .option('--document-slug <slug>', 'Only pull matching document slug (repeatable)', collectRepeatedOption, [])
         .option('--status <value>', 'Document status filter')
@@ -5356,9 +5885,9 @@ export function makeDocCommand() {
     }));
     applyDocContextOptions(cmd
         .command('publish')
-        .description('Materialize saved document content to markdown or html')
+        .description('Materialize saved document content to markdown, html, or exact source')
         .requiredOption('--document-version-id <id>', 'Document version id')
-        .option('--target <target>', 'Publish target: markdown or html', 'markdown')
+        .option('--target <target>', 'Publish target: markdown, html, or source', 'markdown')
         .option('--out <path>', 'Write materialized content to a file path')
         .option('--section-id <id>', 'Section id')
         .option('--page-version-id <id>', 'Page version id')