@ontologie/cli 0.1.0-preview.1

package/dist/commands/schema.js

@@ -0,0 +1,933 @@
+/**
+ * ontologie schema -- export, diff, push, pull, check, describe, search
+ *
+ * Rule: stdout = command result, stderr = diagnostics/progress.
+ * Machine-readable formats never mix human diagnostics into stdout.
+ *
+ * Fixes over V2:
+ * - schema describe resolves interfaces, linkTypes, and actions (not just objectTypes)
+ * - schema check outputs structured JSON on stdout (not just stderr)
+ * - schema search validates --types against allowed values
+ * - schema pull creates parent directories before writing
+ * - schema push refuses incomplete remote manifest (no silent action duplication)
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { resolveConfig } from '../config.js';
+import { createDfClient } from '../client.js';
+import { buildCliMeta, extractMetaFromHeaders } from '../output/meta.js';
+import { output, resolveFormat } from '../output/formatter.js';
+import { withErrorHandler } from './shared.js';
+import { compile, diff, formatDiff, planPush, executePush, emitSchema, generateLockfile, verifyLockfile, parseLockfile, serializeLockfile, } from '@dataforge/schema';
+// Schema modules
+import { loadSchemaFile } from '../schema/load-schema-file.js';
+import { fetchFullManifest, fetchManifestVersion, isEndpointUnavailable } from '../schema/manifest-client.js';
+import { resolveLockfilePath, writeTextFileAtomic } from '../schema/lockfile.js';
+import { isStructuredFormat, readCommandName, readCommandLabel, failCli } from '../schema/output.js';
+import { getBreakingChanges } from '../schema/breaking-changes.js';
+import { isRecord, readOptionalTextFile } from '../schema/helpers.js';
+import { getExitCode, CliUsageError, redactSecretsDeep } from '../output/errors.js';
+const DEFAULT_SCHEMA_FILE = 'dataforge.schema.ts';
+// ---------------------------------------------------------------------------
+// Deterministic diff sorting
+// ---------------------------------------------------------------------------
+function compareStable(a, b) {
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+}
+export function sortDiffChanges(changes) {
+    return [...changes].sort((a, b) => {
+        const e = compareStable(a.entity ?? '', b.entity ?? '');
+        if (e !== 0)
+            return e;
+        const n = compareStable(a.name ?? '', b.name ?? '');
+        if (n !== 0)
+            return n;
+        return compareStable(a.kind ?? '', b.kind ?? '');
+    });
+}
+// ---------------------------------------------------------------------------
+// Search type validation
+// ---------------------------------------------------------------------------
+export const ALLOWED_SEARCH_TYPES = new Set(['ObjectType', 'LinkType', 'Interface', 'Action']);
+export function parseSearchTypes(raw) {
+    const types = [...new Set(raw
+            .split(',')
+            .map((type) => type.trim())
+            .filter(Boolean))];
+    if (types.length === 0) {
+        throw new CliUsageError('At least one schema search type must be provided.', {
+            allowed: [...ALLOWED_SEARCH_TYPES],
+        });
+    }
+    const invalid = types.filter((type) => !ALLOWED_SEARCH_TYPES.has(type));
+    if (invalid.length > 0) {
+        throw new CliUsageError('Invalid schema search type(s).', {
+            invalid,
+            allowed: [...ALLOWED_SEARCH_TYPES],
+        });
+    }
+    return types.join(',');
+}
+// ---------------------------------------------------------------------------
+// Limit validation
+// ---------------------------------------------------------------------------
+export function parseLimit(raw, defaultValue = 20, maxValue = 100) {
+    if (raw === undefined || raw === null || raw === '')
+        return defaultValue;
+    const limit = Number(raw);
+    if (!Number.isInteger(limit) || limit < 1 || limit > maxValue) {
+        throw new CliUsageError(`Invalid --limit value: ${String(raw)}`, {
+            min: 1,
+            max: maxValue,
+            default: defaultValue,
+        });
+    }
+    return limit;
+}
+function findDescribeMatches(manifest, query) {
+    return [
+        ...manifest.objectTypes
+            .filter((t) => t.apiName === query || t.displayName === query)
+            .map((value) => ({ entity: 'objectType', value })),
+        ...manifest.interfaces
+            .filter((i) => i.apiName === query || i.displayName === query)
+            .map((value) => ({ entity: 'interface', value })),
+        ...manifest.linkTypes
+            .filter((l) => l.apiName === query || l.relationshipType === query || l.label === query)
+            .map((value) => ({ entity: 'linkType', value })),
+        ...manifest.actions
+            .filter((a) => a.apiName === query ||
+            a.displayName === query ||
+            (a.objectTypeApiName ? `${a.objectTypeApiName}.${a.apiName}` === query : false))
+            .map((value) => ({ entity: 'action', value })),
+    ];
+}
+// ---------------------------------------------------------------------------
+// Shared local schema compilation
+// ---------------------------------------------------------------------------
+async function compileLocalSchema(schemaPath, config) {
+    const loaded = await loadSchemaFile(schemaPath);
+    const objectTypes = loaded.objectTypes ?? [];
+    const actions = loaded.actions ?? [];
+    const manifest = compile(objectTypes, {
+        workspaceId: config.workspaceId,
+        ...(config.spaceId ? { espaceId: config.spaceId } : {}),
+        actions: actions.length > 0 ? actions : undefined,
+    });
+    return { schemaPath, objectTypes, actions, manifest };
+}
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+export function registerSchema(program) {
+    const schema = program
+        .command('schema')
+        .description('Ontology schema operations');
+    const getFormat = () => {
+        const f = program.opts();
+        return f.format === 'json' ? 'json' : f.format === 'jsonl' ? 'jsonl' : 'text';
+    };
+    schema
+        .command('export')
+        .description('Export full ontology manifest')
+        .action((opts) => withErrorHandler(() => runSchemaExport(program, opts), getFormat)());
+    schema
+        .command('describe [typeName]')
+        .description('Describe ontology schema — all types or a specific type (objectType, linkType, interface, or action)')
+        .action((typeName, opts) => withErrorHandler(() => runSchemaDescribe(program, typeName, opts), getFormat)());
+    schema
+        .command('search <query>')
+        .description('Search ontology types and properties by keyword')
+        .option('--types <types>', 'Filter by node type (ObjectType, LinkType, Interface, Action)', 'ObjectType,LinkType')
+        .option('--limit <n>', 'Maximum number of results (1-100)', '20')
+        .option('--include-properties', 'Include property details in results')
+        .action((query, opts) => withErrorHandler(() => runSchemaSearch(program, query, opts), getFormat)());
+    schema
+        .command('diff')
+        .description('Compare local dataforge.schema.ts against remote ontology')
+        .option('--schema <path>', 'Path to schema file', DEFAULT_SCHEMA_FILE)
+        .option('--exit-code', 'Exit with SCHEMA_DRIFT_ERROR when differences are found', false)
+        .action((opts) => withErrorHandler(() => runSchemaDiff(program, opts), getFormat)());
+    schema
+        .command('push')
+        .description('Push local schema changes to remote ontology')
+        .option('--schema <path>', 'Path to schema file', DEFAULT_SCHEMA_FILE)
+        .option('--yes', 'Skip confirmation prompt', false)
+        .option('--dry-run', 'Show plan without executing', false)
+        .option('--allow-breaking', 'Allow destructive schema changes', false)
+        .option('--include-payload', 'Include full command payload in dry-run output', false)
+        .action((opts) => withErrorHandler(() => runSchemaPush(program, opts), getFormat)());
+    schema
+        .command('pull')
+        .description('Generate dataforge.schema.ts from remote ontology')
+        .option('--output <path>', 'Output file path', DEFAULT_SCHEMA_FILE)
+        .option('--force', 'Overwrite output file if it already exists', false)
+        .action((opts) => withErrorHandler(() => runSchemaPull(program, opts), getFormat)());
+    schema
+        .command('check')
+        .description('Compile schema and verify lockfile integrity')
+        .option('--schema <path>', 'Path to schema file', DEFAULT_SCHEMA_FILE)
+        .option('--fail-on-drift', 'Compare lockfile manifestVersion vs remote and exit 1 on mismatch', false)
+        .action((opts) => withErrorHandler(() => runSchemaCheck(program, opts), getFormat)());
+}
+// ---------------------------------------------------------------------------
+// schema export — full manifest via fetchFullManifest
+// ---------------------------------------------------------------------------
+async function runSchemaExport(program, _opts) {
+    const flags = program.opts();
+    const effectiveFlags = {
+        ...flags,
+        format: flags.format ?? (process.stdout.isTTY ? 'yaml' : flags.format),
+    };
+    const config = resolveConfig(flags);
+    const client = createDfClient(config);
+    const manifest = await fetchFullManifest(client, config);
+    let stats;
+    try {
+        stats = await client.transport.request({
+            method: 'GET',
+            path: '/api/v1/ontology/stats',
+            query: config.spaceId ? { espaceId: config.spaceId } : undefined,
+        });
+    }
+    catch (error) {
+        if (!isEndpointUnavailable(error)) {
+            process.stderr.write(`Warning: could not fetch ontology stats: ${String(error)}\n`);
+        }
+    }
+    const schemaExport = {
+        ...manifest,
+        statistics: {
+            objectTypes: manifest.objectTypes.length,
+            linkTypes: manifest.linkTypes.length,
+            interfaces: manifest.interfaces?.length ?? 0,
+            actions: manifest.actions?.length ?? 0,
+            ...(stats ? { server: stats } : {}),
+        },
+    };
+    const meta = buildCliMeta({
+        command: 'schema.export',
+        workspaceId: config.workspaceId,
+        apiUrl: config.apiUrl,
+        manifestVersion: manifest.version ?? null,
+    });
+    output(schemaExport, meta, effectiveFlags);
+}
+// ---------------------------------------------------------------------------
+// schema describe — multi-entity resolution (objectType, linkType, interface, action)
+// ---------------------------------------------------------------------------
+async function runSchemaDescribe(program, typeName, _opts) {
+    const flags = program.opts();
+    const config = resolveConfig(flags);
+    const client = createDfClient(config);
+    const manifest = await fetchFullManifest(client, config);
+    const objectTypes = manifest.objectTypes ?? [];
+    const linkTypes = manifest.linkTypes ?? [];
+    const manifestActions = manifest.actions ?? [];
+    const manifestInterfaces = manifest.interfaces ?? [];
+    const meta = buildCliMeta({
+        command: 'schema.describe',
+        workspaceId: config.workspaceId,
+        apiUrl: config.apiUrl,
+        manifestVersion: manifest.version ?? null,
+    });
+    if (typeName) {
+        const matches = findDescribeMatches({ objectTypes, interfaces: manifestInterfaces, linkTypes, actions: manifestActions }, typeName);
+        // Ambiguity detection
+        if (matches.length > 1) {
+            failCli({
+                code: 'INVALID_USAGE',
+                message: `Schema entity name "${typeName}" is ambiguous.`,
+                details: {
+                    query: typeName,
+                    matches: matches.map((m) => ({
+                        entity: m.entity,
+                        apiName: 'apiName' in m.value ? m.value.apiName : null,
+                        displayName: 'displayName' in m.value ? m.value.displayName : null,
+                    })),
+                    hint: 'Use a fully-qualified action name (e.g. ObjectType.actionName) to disambiguate.',
+                },
+                retryable: false,
+                correlationId: meta.requestId,
+            }, meta, flags);
+            return;
+        }
+        if (matches.length === 1) {
+            const match = matches[0];
+            switch (match.entity) {
+                case 'objectType': {
+                    const ot = match.value;
+                    const properties = ot.properties ?? [];
+                    const outgoing = linkTypes.filter((l) => l.sourceTypeApiName === ot.apiName);
+                    const incoming = linkTypes.filter((l) => l.targetTypeApiName === ot.apiName);
+                    const actions = manifestActions.filter((a) => a.objectTypeApiName === ot.apiName);
+                    output({
+                        entity: 'objectType',
+                        apiName: ot.apiName,
+                        displayName: ot.displayName,
+                        description: ot.description,
+                        primaryKey: ot.primaryKey,
+                        properties: properties.map((p) => ({
+                            name: p.apiName,
+                            dataType: p.dataType,
+                            required: p.required,
+                            indexed: p.indexed,
+                            unique: p.unique,
+                            semanticType: p.semanticType,
+                            description: p.description,
+                        })),
+                        links: {
+                            outgoing: outgoing.map((l) => ({
+                                name: l.apiName.split('__').pop() ?? l.apiName,
+                                target: l.targetTypeApiName,
+                                cardinality: l.cardinality,
+                                label: l.label,
+                            })),
+                            incoming: incoming.map((l) => ({
+                                name: l.inverseName ?? l.apiName,
+                                source: l.sourceTypeApiName,
+                                cardinality: l.cardinality,
+                            })),
+                        },
+                        actions: actions.map((a) => ({
+                            apiName: a.apiName,
+                            displayName: a.displayName,
+                            actionType: a.actionType,
+                            trigger: a.trigger,
+                            parameters: a.parameters?.length ?? 0,
+                            description: a.description,
+                        })),
+                        statistics: {
+                            propertyCount: properties.length,
+                            outgoingLinks: outgoing.length,
+                            incomingLinks: incoming.length,
+                            actionCount: actions.length,
+                        },
+                    }, meta, flags);
+                    return;
+                }
+                case 'interface': {
+                    const iface = match.value;
+                    output({
+                        entity: 'interface',
+                        apiName: iface.apiName,
+                        displayName: iface.displayName,
+                        description: iface.description,
+                        sharedProperties: (iface.sharedProperties ?? []).map((p) => ({
+                            name: p.apiName,
+                            dataType: p.dataType,
+                            required: p.required,
+                            indexed: p.indexed,
+                            unique: p.unique,
+                            semanticType: p.semanticType,
+                            description: p.description,
+                        })),
+                    }, meta, flags);
+                    return;
+                }
+                case 'linkType': {
+                    const link = match.value;
+                    output({
+                        entity: 'linkType',
+                        apiName: link.apiName,
+                        source: link.sourceTypeApiName,
+                        target: link.targetTypeApiName,
+                        cardinality: link.cardinality,
+                        relationshipType: link.relationshipType,
+                        label: link.label,
+                        inverseName: link.inverseName,
+                        properties: link.properties ?? [],
+                    }, meta, flags);
+                    return;
+                }
+                case 'action': {
+                    const action = match.value;
+                    output({
+                        entity: 'action',
+                        apiName: action.apiName,
+                        displayName: action.displayName,
+                        objectTypeApiName: action.objectTypeApiName,
+                        actionType: action.actionType,
+                        trigger: action.trigger,
+                        parameters: action.parameters ?? [],
+                        conditions: action.conditions ?? [],
+                        effects: action.effects ?? [],
+                        requiredScopes: action.requiredScopes ?? [],
+                    }, meta, flags);
+                    return;
+                }
+            }
+        }
+        // Not found
+        failCli({
+            code: 'NOT_FOUND',
+            message: `Schema entity "${typeName}" not found.`,
+            details: {
+                query: typeName,
+                availableObjectTypes: objectTypes.map((t) => t.apiName),
+                availableInterfaces: manifestInterfaces.map((i) => i.apiName),
+                availableLinkTypes: linkTypes.map((l) => l.apiName),
+                availableActions: manifestActions.map((a) => a.objectTypeApiName ? `${a.objectTypeApiName}.${a.apiName}` : a.apiName),
+            },
+            retryable: false,
+            correlationId: meta.requestId,
+        }, meta, flags);
+    }
+    else {
+        // No typeName — describe all entity types
+        const overview = {
+            objectTypes: objectTypes.map((ot) => ({
+                entity: 'objectType',
+                apiName: ot.apiName,
+                displayName: ot.displayName,
+                properties: (ot.properties ?? []).length,
+                outgoingLinks: linkTypes.filter((l) => l.sourceTypeApiName === ot.apiName).length,
+                incomingLinks: linkTypes.filter((l) => l.targetTypeApiName === ot.apiName).length,
+                actions: manifestActions.filter((a) => a.objectTypeApiName === ot.apiName).length,
+                description: ot.description,
+            })),
+            interfaces: manifestInterfaces.map((iface) => ({
+                entity: 'interface',
+                apiName: iface.apiName,
+                displayName: iface.displayName,
+                sharedProperties: (iface.sharedProperties ?? []).length,
+                description: iface.description,
+            })),
+            linkTypes: linkTypes.map((link) => ({
+                entity: 'linkType',
+                apiName: link.apiName,
+                source: link.sourceTypeApiName,
+                target: link.targetTypeApiName,
+                cardinality: link.cardinality,
+                label: link.label,
+            })),
+            actions: manifestActions.map((action) => ({
+                entity: 'action',
+                apiName: action.apiName,
+                displayName: action.displayName,
+                objectTypeApiName: action.objectTypeApiName,
+                actionType: action.actionType,
+            })),
+        };
+        if (isStructuredFormat(flags)) {
+            output(overview, meta, flags);
+        }
+        else {
+            output(overview.objectTypes, meta, flags, [
+                'apiName',
+                'displayName',
+                'properties',
+                'outgoingLinks',
+                'incomingLinks',
+                'actions',
+            ]);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// schema search — validated types
+// ---------------------------------------------------------------------------
+async function runSchemaSearch(program, query, opts) {
+    const flags = program.opts();
+    const config = resolveConfig(flags);
+    const client = createDfClient(config);
+    const validatedTypes = parseSearchTypes(opts.types);
+    const limit = parseLimit(opts.limit);
+    const searchQuery = {
+        q: query,
+        types: validatedTypes,
+        limit,
+    };
+    if (opts.includeProperties) {
+        searchQuery.includeProperties = 'true';
+    }
+    const searchResponse = await client.transport.requestWithHeaders({
+        method: 'GET',
+        path: '/api/v1/ontology/search',
+        query: searchQuery,
+    });
+    const results = searchResponse.data?.results ?? [];
+    const items = results.map((r) => ({
+        apiName: r.api_name || r.name,
+        displayName: r.displayName || r.name,
+        type: r.type,
+        score: r.score,
+        description: r.description,
+        highlights: r.highlights,
+        ...(opts.includeProperties && r.properties ? { properties: r.properties } : {}),
+    }));
+    const searchHeaderMeta = extractMetaFromHeaders(searchResponse.headers);
+    const meta = buildCliMeta({
+        command: 'schema.search',
+        workspaceId: config.workspaceId,
+        apiUrl: config.apiUrl,
+        ...searchHeaderMeta,
+    });
+    const data = {
+        query: searchResponse.data?.query ?? query,
+        total: searchResponse.data?.total ?? items.length,
+        limit,
+        timingMs: searchResponse.data?.timing_ms ?? null,
+        items,
+    };
+    if (isStructuredFormat(flags)) {
+        output(data, meta, flags);
+    }
+    else {
+        output(items, meta, flags, ['apiName', 'type', 'score', 'description']);
+    }
+}
+// ---------------------------------------------------------------------------
+// schema diff — CSV-aware structured output
+// ---------------------------------------------------------------------------
+async function runSchemaDiff(program, opts) {
+    const flags = program.opts();
+    const config = resolveConfig(flags);
+    const client = createDfClient(config);
+    process.stderr.write('Loading local schema...\n');
+    const local = await compileLocalSchema(opts.schema, config);
+    process.stderr.write('Fetching remote ontology...\n');
+    const remoteManifest = await fetchFullManifest(client, config);
+    const diffResult = diff(local.manifest, remoteManifest);
+    const formatted = formatDiff(diffResult);
+    const meta = buildCliMeta({
+        command: 'schema.diff',
+        workspaceId: config.workspaceId,
+        apiUrl: config.apiUrl,
+        manifestVersion: remoteManifest.version ?? null,
+    });
+    const format = resolveFormat(flags);
+    if (format === 'csv') {
+        output(sortDiffChanges(diffResult.changes ?? []).map((change) => ({
+            kind: change.kind,
+            entity: change.entity,
+            name: change.name,
+            parent: change.parent,
+        })), meta, flags, ['kind', 'entity', 'name', 'parent']);
+    }
+    else if (isStructuredFormat(flags)) {
+        output({
+            hasChanges: diffResult.hasChanges,
+            changes: sortDiffChanges(diffResult.changes ?? []),
+            summary: formatted,
+        }, meta, flags);
+    }
+    else {
+        process.stdout.write(`${formatted}\n`);
+    }
+    if (!diffResult.hasChanges) {
+        process.stderr.write('Local schema is in sync with remote.\n');
+    }
+    if (opts.exitCode && diffResult.hasChanges) {
+        process.exitCode = getExitCode("SCHEMA_DRIFT_ERROR");
+    }
+}
+// ---------------------------------------------------------------------------
+// schema push — convergence-verified, breaking-change-aware, incomplete-guard
+//
+// Confirmation flow: --dry-run shows plan, --yes confirms execution.
+// This is NOT the plan artifact flow (--apply-plan + --idempotency-key).
+// ---------------------------------------------------------------------------
+async function runSchemaPush(program, opts) {
+    const flags = program.opts();
+    const config = resolveConfig(flags);
+    const client = createDfClient(config);
+    const meta = buildCliMeta({
+        command: 'schema.push',
+        workspaceId: config.workspaceId,
+        apiUrl: config.apiUrl,
+    });
+    process.stderr.write('Loading local schema...\n');
+    const local = await compileLocalSchema(opts.schema, config);
+    process.stderr.write('Fetching remote ontology...\n');
+    const remoteManifest = await fetchFullManifest(client, config);
+    // Guard: refuse push when remote manifest was obtained via fallback
+    // (actions endpoint unavailable). We check via the MANIFEST_FALLBACK warning
+    // injected by fetchFullManifest, which indicates the /manifest endpoint
+    // returned 404/5xx and actions are not available in fallback mode.
+    // Only block when local schema actually defines actions.
+    const manifestFallbackUsed = !remoteManifest.actions || ((local.manifest.actions?.length ?? 0) > 0 &&
+        (remoteManifest.actions?.length ?? 0) === 0 &&
+        remoteManifest.version === '1.0' // fallback always returns version '1.0'
+    );
+    if (manifestFallbackUsed &&
+        (local.manifest.actions?.length ?? 0) > 0) {
+        failCli({
+            code: 'PRECONDITION_FAILED',
+            message: 'Remote manifest is incomplete: actions endpoint unavailable.',
+            details: {
+                hint: 'Retry when the ontology actions endpoint is available, or verify the remote has no actions before pushing.',
+            },
+            retryable: true,
+            correlationId: meta.requestId,
+        }, meta, flags);
+        return;
+    }
+    const diffResult = diff(local.manifest, remoteManifest);
+    if (!diffResult.hasChanges) {
+        output({
+            changed: false,
+            executed: false,
+            message: 'No changes to push. Schema is in sync.',
+        }, meta, flags);
+        return;
+    }
+    const commands = planPush(diffResult, remoteManifest, {
+        workspaceId: config.workspaceId,
+        espaceId: config.spaceId,
+    });
+    // Guard: diff says changes, but planner produced no commands
+    if (commands.length === 0) {
+        failCli({
+            code: 'INTERNAL_ERROR',
+            message: 'Diff contains changes, but planner produced no commands.',
+            details: {
+                hint: 'This usually means planPush does not support one or more diff change kinds.',
+                changes: diffResult.changes ?? [],
+                summary: formatDiff(diffResult),
+            },
+            retryable: false,
+            correlationId: meta.requestId,
+        }, meta, flags);
+        return;
+    }
+    // Breaking changes check — consistent for both dry-run and real push
+    const breakingChanges = getBreakingChanges(diffResult);
+    const canRun = breakingChanges.length === 0 || opts.allowBreaking;
+    const dryRunData = {
+        canRun,
+        changed: true,
+        executed: false,
+        commandCount: commands.length,
+        plannedChanges: commands.map((cmd) => ({
+            action: cmd.type,
+            name: readCommandName(cmd.payload),
+            ...(opts.includePayload ? { payload: redactSecretsDeep(cmd.payload) } : {}),
+        })),
+        breakingChanges,
+        requiredScopes: ['schema.write'],
+        estimatedCostUnits: commands.length,
+        summary: formatDiff(diffResult),
+    };
+    if (opts.dryRun) {
+        output(dryRunData, meta, flags);
+        if (!canRun) {
+            process.exitCode = getExitCode("PRECONDITION_FAILED");
+        }
+        return;
+    }
+    if (!canRun) {
+        failCli({
+            code: 'PRECONDITION_FAILED',
+            message: 'Breaking changes detected.',
+            details: {
+                breakingChanges,
+                hint: 'Pass --allow-breaking to execute destructive schema changes.',
+            },
+            retryable: false,
+            correlationId: meta.requestId,
+        }, meta, flags);
+        return;
+    }
+    if (!opts.yes) {
+        failCli({
+            code: 'CONFIRMATION_REQUIRED',
+            message: `This operation will execute ${commands.length} command(s). Pass --yes to confirm.`,
+            details: {
+                prompt: `Execute ${commands.length} schema change(s)?`,
+                affectedCount: commands.length,
+                affectedEntities: commands.map(readCommandLabel),
+            },
+            retryable: false,
+            correlationId: meta.requestId,
+        }, meta, flags);
+        return;
+    }
+    // Concurrency check: verify remote hasn't changed since we fetched it
+    try {
+        const latestVersion = await fetchManifestVersion(client, config);
+        if (remoteManifest.version && latestVersion !== remoteManifest.version) {
+            failCli({
+                code: 'CONFLICT_ERROR',
+                message: 'Remote manifest changed while preparing schema push.',
+                details: {
+                    expectedManifestVersion: remoteManifest.version,
+                    actualManifestVersion: latestVersion,
+                    hint: 'Re-run schema diff and schema push.',
+                },
+                retryable: true,
+                correlationId: meta.requestId,
+            }, meta, flags);
+            return;
+        }
+    }
+    catch {
+        // If version endpoint is unavailable, proceed without concurrency check
+    }
+    // Show human diff only for non-structured formats
+    if (!isStructuredFormat(flags)) {
+        process.stdout.write(`${formatDiff(diffResult)}\n\n`);
+    }
+    process.stderr.write(`Executing ${commands.length} schema command(s)...\n`);
+    const pushResult = await executePush({
+        transport: client.transport,
+        commands,
+        onProgress: (progress) => {
+            process.stderr.write(`  [${progress.completed}/${progress.total}] ${progress.current}\n`);
+        },
+    });
+    if (pushResult.failed > 0) {
+        failCli({
+            code: 'INTERNAL_ERROR',
+            message: `Schema push partially failed: ${pushResult.failed} command(s) failed.`,
+            details: {
+                succeeded: pushResult.succeeded,
+                failed: pushResult.failed,
+                errors: pushResult.errors.map((error) => ({
+                    command: error.command.type,
+                    message: String(error.error),
+                })),
+            },
+            retryable: false,
+            correlationId: meta.requestId,
+        }, meta, flags);
+        return;
+    }
+    // Post-push convergence check
+    process.stderr.write('Refreshing remote manifest...\n');
+    const refreshedManifest = await fetchFullManifest(client, config);
+    const postPushDiff = diff(local.manifest, refreshedManifest);
+    if (postPushDiff.hasChanges) {
+        failCli({
+            code: 'INTERNAL_ERROR',
+            message: 'Remote manifest still differs from local schema after push.',
+            details: {
+                succeeded: pushResult.succeeded,
+                failed: pushResult.failed,
+                converged: false,
+                remainingChanges: postPushDiff.changes ?? [],
+                summary: formatDiff(postPushDiff),
+            },
+            retryable: true,
+            correlationId: meta.requestId,
+        }, meta, flags);
+        return;
+    }
+    // Lockfile from verified server manifest
+    const lockContent = generateLockfile(refreshedManifest);
+    const lockPath = resolveLockfilePath(opts.schema);
+    await fs.promises.mkdir(path.dirname(lockPath), { recursive: true });
+    await writeTextFileAtomic(lockPath, serializeLockfile(lockContent));
+    output({
+        changed: true,
+        executed: true,
+        converged: true,
+        succeeded: pushResult.succeeded,
+        failed: pushResult.failed,
+        commandCount: commands.length,
+        manifestVersion: refreshedManifest.version,
+        lockfile: lockPath,
+    }, meta, flags);
+}
+// ---------------------------------------------------------------------------
+// schema pull — --force, directory check, mkdir parent, process.exitCode
+// ---------------------------------------------------------------------------
+async function runSchemaPull(program, opts) {
+    const flags = program.opts();
+    const config = resolveConfig(flags);
+    const client = createDfClient(config);
+    const meta = buildCliMeta({
+        command: 'schema.pull',
+        workspaceId: config.workspaceId,
+        apiUrl: config.apiUrl,
+    });
+    // Check output path BEFORE making network calls
+    const outputPath = path.resolve(opts.output);
+    try {
+        const stat = await fs.promises.stat(outputPath);
+        if (stat.isDirectory()) {
+            failCli({
+                code: 'PRECONDITION_FAILED',
+                message: `Output path is a directory: ${outputPath}`,
+                details: { outputPath },
+                retryable: false,
+                correlationId: meta.requestId,
+            }, meta, flags);
+            return;
+        }
+        if (!opts.force) {
+            failCli({
+                code: 'PRECONDITION_FAILED',
+                message: `File already exists: ${outputPath}`,
+                details: {
+                    outputPath,
+                    hint: 'Pass --force to overwrite it.',
+                },
+                retryable: false,
+                correlationId: meta.requestId,
+            }, meta, flags);
+            return;
+        }
+    }
+    catch (error) {
+        const code = isRecord(error) ? error.code : undefined;
+        if (code !== 'ENOENT') {
+            throw error;
+        }
+        // File doesn't exist — proceed
+    }
+    process.stderr.write('Fetching remote ontology...\n');
+    const remoteManifest = await fetchFullManifest(client, config);
+    const source = emitSchema(remoteManifest);
+    // Ensure parent directory exists
+    await fs.promises.mkdir(path.dirname(outputPath), { recursive: true });
+    await writeTextFileAtomic(outputPath, source);
+    const lockPath = resolveLockfilePath(outputPath);
+    await fs.promises.mkdir(path.dirname(lockPath), { recursive: true });
+    const lockContent = generateLockfile(remoteManifest);
+    await writeTextFileAtomic(lockPath, serializeLockfile(lockContent));
+    output({
+        written: true,
+        schemaFile: outputPath,
+        lockfile: lockPath,
+        version: remoteManifest.version,
+        objectTypes: remoteManifest.objectTypes.length,
+        linkTypes: remoteManifest.linkTypes.length,
+        actions: remoteManifest.actions?.length ?? 0,
+    }, meta, flags);
+}
+// ---------------------------------------------------------------------------
+// schema check — structured output on stdout, --fail-on-drift
+// ---------------------------------------------------------------------------
+async function runSchemaCheck(program, opts) {
+    const flags = program.opts();
+    const config = resolveConfig(flags);
+    const meta = buildCliMeta({
+        command: 'schema.check',
+        workspaceId: config.workspaceId,
+        apiUrl: config.apiUrl,
+    });
+    const result = {
+        valid: false,
+        schemaFile: opts.schema,
+        compiled: null,
+        lockfile: {
+            present: false,
+            drifted: null,
+        },
+        remote: {
+            checked: false,
+            drifted: null,
+        },
+    };
+    process.stderr.write('Loading local schema...\n');
+    const local = await compileLocalSchema(opts.schema, config);
+    const manifest = local.manifest;
+    result.compiled = {
+        objectTypes: manifest.objectTypes.length,
+        linkTypes: manifest.linkTypes.length,
+        actions: manifest.actions.length,
+    };
+    process.stderr.write(`Compiled: ${manifest.objectTypes.length} type(s), ${manifest.linkTypes.length} link(s), ${manifest.actions.length} action(s)\n`);
+    // Verify lockfile if it exists (async FS)
+    const lockPath = resolveLockfilePath(opts.schema);
+    const lockRaw = await readOptionalTextFile(lockPath);
+    if (lockRaw !== null) {
+        let lockContent;
+        try {
+            lockContent = parseLockfile(lockRaw);
+        }
+        catch {
+            result.lockfile = {
+                present: true,
+                path: lockPath,
+                drifted: true,
+                reason: 'invalid_lockfile',
+            };
+            failCli({
+                code: 'SCHEMA_DRIFT_ERROR',
+                message: 'Schema lockfile is invalid or unreadable.',
+                details: {
+                    path: lockPath,
+                    hint: 'Run `dataforge schema pull --force` or regenerate the lockfile.',
+                },
+                retryable: false,
+                correlationId: meta.requestId,
+            }, meta, flags);
+            return;
+        }
+        const { drifted } = verifyLockfile(lockContent, manifest);
+        if (drifted) {
+            result.lockfile = {
+                present: true,
+                path: lockPath,
+                drifted: true,
+            };
+            process.stderr.write('Lockfile DRIFT detected — schema has changed since last push/pull.\n');
+            process.stderr.write('Run `dataforge schema push` to sync, or `dataforge schema pull` to reset.\n');
+            output(result, meta, flags);
+            process.exitCode = getExitCode("SCHEMA_DRIFT_ERROR");
+            return;
+        }
+        result.lockfile = {
+            present: true,
+            path: lockPath,
+            drifted: false,
+        };
+        process.stderr.write('Lockfile OK — no drift detected.\n');
+        // --fail-on-drift: strict remote check
+        if (opts.failOnDrift) {
+            if (!lockContent.manifestVersion) {
+                result.remote = {
+                    checked: true,
+                    drifted: true,
+                    reason: 'lockfile has no manifestVersion',
+                };
+                process.stderr.write('DRIFT: lockfile has no manifestVersion; cannot compare with remote.\n');
+                output(result, meta, flags);
+                process.exitCode = getExitCode("SCHEMA_DRIFT_ERROR");
+                return;
+            }
+            const client = createDfClient(config);
+            const remoteVersion = await fetchManifestVersion(client, config);
+            if (lockContent.manifestVersion !== remoteVersion) {
+                result.remote = {
+                    checked: true,
+                    drifted: true,
+                    localManifestVersion: lockContent.manifestVersion,
+                    remoteManifestVersion: remoteVersion,
+                };
+                process.stderr.write(`DRIFT: local lockfile version ${lockContent.manifestVersion} differs from remote manifest ${remoteVersion}\n`);
+                output(result, meta, flags);
+                process.exitCode = getExitCode("SCHEMA_DRIFT_ERROR");
+                return;
+            }
+            result.remote = {
+                checked: true,
+                drifted: false,
+                manifestVersion: remoteVersion,
+            };
+            process.stderr.write(`OK: local and remote versions match (${remoteVersion})\n`);
+        }
+    }
+    else {
+        result.lockfile = {
+            present: false,
+            drifted: null,
+        };
+        process.stderr.write('No lockfile found. Run `dataforge schema push` or `dataforge schema pull` to generate one.\n');
+        if (opts.failOnDrift) {
+            output(result, meta, flags);
+            process.exitCode = getExitCode("SCHEMA_DRIFT_ERROR");
+            return;
+        }
+    }
+    result.valid = true;
+    process.stderr.write('Schema check passed.\n');
+    output(result, meta, flags);
+}
+//# sourceMappingURL=schema.js.map