@software-dlc/cli 0.157.2

package/dist/cli.js

@@ -0,0 +1,1004 @@
+#!/usr/bin/env node
+import './quiet-warnings.js';
+import { uploadHostedWorktreeMedia } from './local/media-upload.js';
+import { trackPendingOperation, currentOperation } from './local/operation.js';
+import { runCliOperation } from './cli-operation.js';
+import { inspectSnapshotCommand } from './cli-snapshot.js';
+import { branchApplyCommand, branchCommitCommand, pullRequestCommand } from './cli-branch-history.js';
+import { branchesCommand, unboundBranchError } from './cli-branches.js';
+import { argumentValue, argumentValues, hasArgument, requiredArgument, explicitGraphTarget, optionalIntegerArgument } from './cli-arguments.js';
+import { isAutoMergePreflightClean, readAutoMergeScopeRecipes } from './local/aggregate-preflight.js';
+import { parseGraphFileSaveMode, runCliMetaCommand, viewHelpRequested, SDLC_CLI_USAGE } from './cli-help.js';
+import { runCliDeploy } from './cli-deploy.js';
+import { runCliLogin } from './cli-login.js';
+import { loadViewModule, viewMissing } from './view-seam.js';
+import { runPackagesCommand } from './packages-cli.js';
+import { readFile } from 'node:fs/promises';
+import { basename, extname } from 'node:path';
+import { portable_graph_schema } from '@software-dlc/graph/schema';
+import { compareGraphPayloads, compareGraphSubgraphs, compareGraphWorkspace, ensureBranchWorktree } from '@software-dlc/graph/client';
+import { runAllowMcpCommand } from './local/allow-mcp.js';
+import { runOrgCommand } from './cli-org.js';
+import { sdlcPlatformFetch } from './local/api-client.js';
+import { readRepositoryConfig, rebindRepositoryConfig } from './local/config.js';
+import { initializeEnvironmentProfile, resolveActiveEnvironmentContext, resolveEnvironmentClient } from './local/environment-context.js';
+import { addTrustedConnection, getTrustedConnection, listEnvironmentProfiles, listTrustedConnections, migrateLegacyLocalSidecar, normalizeEnvironmentProfile, normalizeServiceOrigin, readActiveEnvironmentSelector, readEnvironmentMetadata, readEnvironmentSwitchJournal } from './local/environment-sidecar.js';
+import { recoverEnvironmentSwitch, switchEnvironment, withActiveEnvironmentOperation } from './local/environment-switch.js';
+import { excludeEnvironmentPaths } from './local/environment-exclude.js';
+import { discoverGitWorktree } from './local/git.js';
+import { checkoutWorktreeProjection, adoptWorktreeProjection, getManagedProjectionStatus, requireManagedProjectionCompleteness, refreshWorktreeProjection, removeManagedProjectionEntity, saveManagedProjection, syncManagedProjection } from './local/worktree-projection.js';
+import { composeGraphProjection } from './local/projection.js';
+import { rebuildCommand } from './cli-rebuild.js';
+import { resetCommand } from './cli-reset.js';
+import { resolveLocalScopeImpact } from './local/scope-impact.js';
+import { recoverManagedProjectionFromStalePending } from './local/pending-recovery.js';
+import { LocalSdlcStore } from './local/store.js';
+import { TreeSaveStillFinalizingError } from './local/tree-save.js';
+import { prepareLocalStateDirectory } from './local/state-directory.js';
+import { saveLiveWorktreeChange, syncPendingWorktreeChanges } from './local/sync.js';
+import { isLocalWorkspaceCommand, runLocalWorkspaceCommand } from './local/workspace-cli.js';
+function parsePortableGraph(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Graph file contains invalid JSON: ${message}`);
+    }
+    return portable_graph_schema.parse(parsed);
+}
+async function readPortableGraphFile(path) {
+    return parsePortableGraph(await readFile(path, 'utf8'));
+}
+function resolveClient(args, environment) {
+    const client = resolveEnvironmentClient({
+        context: environment,
+        fetch_impl: sdlcPlatformFetch()
+    });
+    const explicit_base_url = argumentValue(args, '--base-url');
+    if (explicit_base_url &&
+        normalizeServiceOrigin(explicit_base_url) !== client.base_url) {
+        throw new Error('--base-url cannot select a different origin from the active trusted connection.');
+    }
+    return client;
+}
+function printJson(value) {
+    console.log(JSON.stringify(value, null, 2));
+}
+function isMissingPathError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'ENOENT');
+}
+function trustedConnectionSummary(connection) {
+    return {
+        connection_id: connection.connection_id,
+        name: connection.name,
+        base_url: connection.base_url,
+        origin_fingerprint: connection.origin_fingerprint,
+        credential_env: connection.credential_env
+    };
+}
+async function runConnectionCommand(input) {
+    if (input.subcommand === 'add') {
+        const name = input.args.find((argument) => !argument.startsWith('--'));
+        if (!name) {
+            throw new Error('Usage: sdlc connection add <name> --url <origin> --credential-env <ENV_NAME>');
+        }
+        const connection = await addTrustedConnection({
+            name,
+            base_url: requiredArgument(input.args, '--url'),
+            credential_env: requiredArgument(input.args, '--credential-env')
+        });
+        printJson({ connection: trustedConnectionSummary(connection) });
+        return;
+    }
+    if (input.subcommand === 'list') {
+        printJson({
+            connections: (await listTrustedConnections()).map(trustedConnectionSummary)
+        });
+        return;
+    }
+    throw new Error('Usage: sdlc connection add <name> --url <origin> --credential-env <ENV_NAME> | sdlc connection list');
+}
+async function runEnvironmentCommand(input) {
+    if (input.subcommand === 'use' || input.subcommand === 'recover') {
+        await runEnvironmentCommandUnlocked(input);
+        return;
+    }
+    await withActiveEnvironmentOperation({
+        git: input.git,
+        operation: `cli:env-${input.subcommand ?? 'unknown'}`,
+        run: () => runEnvironmentCommandUnlocked(input)
+    });
+}
+async function runEnvironmentCommandUnlocked(input) {
+    if (input.subcommand === 'add') {
+        const profile_argument = input.args.find((argument) => !argument.startsWith('--'));
+        if (!profile_argument) {
+            throw new Error('Usage: sdlc env add <profile> --connection <name> --repository-id <uuid>');
+        }
+        const profile = normalizeEnvironmentProfile(profile_argument);
+        const connection = await getTrustedConnection({
+            name_or_id: requiredArgument(input.args, '--connection')
+        });
+        printJson({
+            environment: await initializeEnvironmentProfile({
+                git: input.git,
+                profile,
+                repository_id: requiredArgument(input.args, '--repository-id'),
+                connection
+            })
+        });
+        return;
+    }
+    if (input.subcommand === 'migrate') {
+        if (await readEnvironmentSwitchJournal(input.git.repository_root)) {
+            throw new Error('Complete or recover the pending environment switch before migration.');
+        }
+        const connection = await getTrustedConnection({
+            name_or_id: requiredArgument(input.args, '--connection')
+        });
+        await readRepositoryConfig(input.git.repository_root);
+        if (process.env.SDLC_STATE_DIR &&
+            process.env.SDLC_STATE_PROFILE !== 'local') {
+            throw new Error('Migrating legacy external state requires SDLC_STATE_PROFILE=local.');
+        }
+        const legacy_state = await prepareLocalStateDirectory({
+            repository_root: input.git.repository_root,
+            git_dir: input.git.git_dir,
+            override: process.env.SDLC_STATE_DIR
+        });
+        const legacy_store = await LocalSdlcStore.open(legacy_state.state_dir);
+        try {
+            if (legacy_store.hasPendingChanges()) {
+                throw new Error('Legacy local state has pending save/sync work and cannot be migrated.');
+            }
+        }
+        finally {
+            legacy_store.close();
+        }
+        const excluded = await excludeEnvironmentPaths({
+            repository_root: input.git.repository_root,
+            git_common_dir: input.git.git_common_dir,
+            profile: 'local'
+        });
+        printJson({
+            migration: await migrateLegacyLocalSidecar({
+                repository_root: input.git.repository_root,
+                connection
+            }),
+            excluded
+        });
+        return;
+    }
+    if (input.subcommand === 'use') {
+        const profile_argument = input.args.find((argument) => !argument.startsWith('--'));
+        if (!profile_argument) {
+            throw new Error('Usage: sdlc env use <profile>');
+        }
+        const target_profile = normalizeEnvironmentProfile(profile_argument);
+        // Also covers repositories set up before init excluded these paths.
+        const excluded = await excludeEnvironmentPaths({
+            repository_root: input.git.repository_root,
+            git_common_dir: input.git.git_common_dir,
+            profile: target_profile
+        });
+        printJson({
+            environment: await switchEnvironment({
+                git: input.git,
+                target_profile
+            }),
+            excluded
+        });
+        return;
+    }
+    if (input.subcommand === 'recover') {
+        printJson({
+            environment: await recoverEnvironmentSwitch({ git: input.git })
+        });
+        return;
+    }
+    if (input.subcommand === 'current') {
+        const environment = await resolveActiveEnvironmentContext({
+            git: input.git,
+            state_override: process.env.SDLC_STATE_DIR
+        });
+        printJson({
+            profile: environment.profile,
+            sidecar_dir: environment.sidecar_dir,
+            repository_id: environment.config.repository_id,
+            connection: environment.connection
+                ? trustedConnectionSummary(environment.connection)
+                : null,
+            legacy_migration_required: environment.legacy_migration_required
+        });
+        return;
+    }
+    if (input.subcommand === 'list') {
+        const selector = await readActiveEnvironmentSelector(input.git.repository_root);
+        const profiles = await Promise.all((await listEnvironmentProfiles(input.git.repository_root)).map(async ({ profile, sidecar_dir }) => {
+            try {
+                const metadata = await readEnvironmentMetadata(sidecar_dir);
+                const connection = await getTrustedConnection({
+                    name_or_id: metadata.connection_id
+                });
+                const config = await readRepositoryConfig(input.git.repository_root, sidecar_dir);
+                return {
+                    profile,
+                    active: selector?.profile === profile,
+                    sidecar_dir,
+                    repository_id: config.repository_id,
+                    connection: trustedConnectionSummary(connection),
+                    legacy_migration_required: false
+                };
+            }
+            catch (error) {
+                if (profile !== 'live' || selector || !isMissingPathError(error)) {
+                    throw error;
+                }
+                const config = await readRepositoryConfig(input.git.repository_root, sidecar_dir);
+                return {
+                    profile: 'local',
+                    active: true,
+                    sidecar_dir,
+                    repository_id: config.repository_id,
+                    connection: null,
+                    legacy_migration_required: true
+                };
+            }
+        }));
+        printJson({
+            active_profile: selector?.profile ??
+                (profiles.some((profile) => profile.legacy_migration_required)
+                    ? 'local'
+                    : null),
+            profiles
+        });
+        return;
+    }
+    throw new Error('Usage: sdlc env add <profile> --connection <name> --repository-id <uuid> | env migrate --connection <name> | env use <profile> | env recover | env current | env list');
+}
+function imageMimeFromPath(path) {
+    switch (extname(path).toLowerCase()) {
+        case '.png':
+            return 'image/png';
+        case '.jpg':
+        case '.jpeg':
+            return 'image/jpeg';
+        case '.gif':
+            return 'image/gif';
+        case '.webp':
+            return 'image/webp';
+        default:
+            throw new Error('Media upload supports PNG, JPEG, GIF, and WebP files.');
+    }
+}
+function requireBinding(binding) {
+    if (!binding)
+        throw unboundBranchError();
+    return binding;
+}
+async function main() {
+    const view_help = viewHelpRequested(process.argv.slice(2)) ? await loadViewModule() : null;
+    if (runCliMetaCommand(process.argv.slice(2), { viewUsage: view_help?.SDLC_VIEW_USAGE })) {
+        return;
+    }
+    if (await runCliLogin(process.argv.slice(2))) {
+        return;
+    }
+    const deploy_exit = await runCliDeploy(process.argv.slice(2));
+    if (deploy_exit !== null) {
+        process.exitCode = deploy_exit;
+        return;
+    }
+    const [, , command, subcommand, ...rest] = process.argv;
+    if (command === 'view') {
+        // The view's code ships with @software-dlc/agents, not the public CLI (view-seam.ts).
+        const view = await loadViewModule();
+        process.exitCode = view ? await view.runViewCommand(process.argv.slice(3)) : viewMissing(process.cwd());
+        return;
+    }
+    if (command === 'packages') {
+        process.exitCode = await runPackagesCommand(process.argv.slice(3));
+        return;
+    }
+    if (command === 'allow-mcp') {
+        process.exitCode = await runAllowMcpCommand(process.argv.slice(3));
+        return;
+    }
+    if (command === 'org') {
+        process.exitCode = await runOrgCommand(process.argv.slice(3));
+        return;
+    }
+    if (isLocalWorkspaceCommand(command, subcommand)) {
+        await runLocalWorkspaceCommand({
+            command,
+            subcommand,
+            args: command === 'viewer'
+                ? [subcommand, ...rest].filter((value) => typeof value === 'string')
+                : rest
+        });
+        return;
+    }
+    const command_args = [subcommand, ...rest].filter((value) => typeof value === 'string');
+    if (command === 'connection') {
+        await runConnectionCommand({ subcommand, args: rest });
+        return;
+    }
+    const git = await discoverGitWorktree();
+    if (command === 'env') {
+        await runEnvironmentCommand({ git, subcommand, args: rest });
+        return;
+    }
+    if (command === 'init') {
+        await withActiveEnvironmentOperation({
+            git,
+            operation: 'cli:init',
+            run: async () => {
+                const profile = normalizeEnvironmentProfile(argumentValue(command_args, '--profile') ?? 'live');
+                const connection = await getTrustedConnection({
+                    name_or_id: requiredArgument(command_args, '--connection')
+                });
+                const environment = await initializeEnvironmentProfile({
+                    git,
+                    profile,
+                    repository_id: requiredArgument(command_args, '--repository-id'),
+                    connection
+                });
+                printJson({ initialized: true, environment });
+            }
+        });
+        return;
+    }
+    await withActiveEnvironmentOperation({
+        git,
+        operation: `cli:${command ?? 'unknown'}`,
+        run: async () => {
+            const environment = await resolveActiveEnvironmentContext({
+                git,
+                state_override: process.env.SDLC_STATE_DIR
+            });
+            const { config } = environment;
+            if (command === 'snapshot') {
+                printJson(await inspectSnapshotCommand({
+                    args: command_args,
+                    client: resolveClient(command_args, environment),
+                    project_id: config.repository_id
+                }));
+                return;
+            }
+            if (command === 'pr') {
+                const result = await pullRequestCommand({
+                    args: command_args,
+                    client: resolveClient([], environment),
+                    project_id: config.repository_id
+                });
+                printJson(result.output);
+                if (result.exit_code !== 0)
+                    process.exitCode = result.exit_code;
+                return;
+            }
+            const state_resolution = environment.state;
+            const { state_dir } = state_resolution;
+            console.error(`[sdlc] ${environment.profile} state (${state_resolution.source}): ${state_dir}`);
+            if (state_resolution.warning) {
+                console.error(`[sdlc] warning: ${state_resolution.warning}`);
+            }
+            const store = await LocalSdlcStore.open(state_dir);
+            try {
+                const branch_binding = git.ref ? store.getBranchBinding(git.ref) : null;
+                if (command === 'reconnect') {
+                    if (!git.ref) {
+                        throw new Error('Detached HEAD cannot reconnect to an SDLC branch.');
+                    }
+                    if (!hasArgument(command_args, '--adopt-projection')) {
+                        throw new Error('Reconnect requires --adopt-projection to preserve and explicitly adopt the existing sdlc/ graph.');
+                    }
+                    const expected_project_id = requiredArgument(command_args, '--expected-project-id');
+                    const project_id = requiredArgument(command_args, '--project-id');
+                    const branch_id = requiredArgument(command_args, '--branch-id');
+                    if (config.repository_id !== expected_project_id &&
+                        config.repository_id !== project_id) {
+                        throw new Error(`SDLC project association changed: expected ${expected_project_id} or ${project_id}, found ${config.repository_id}.`);
+                    }
+                    const client = resolveClient(command_args, environment);
+                    const ensured = await ensureBranchWorktree(client, branch_id);
+                    if (ensured.branch_id !== branch_id ||
+                        ensured.project_id !== project_id) {
+                        throw new Error('Initialized worktree does not belong to the requested project and branch.');
+                    }
+                    const status = await adoptWorktreeProjection({
+                        store,
+                        client,
+                        worktree_id: ensured.worktree.id,
+                        repository_root: git.repository_root,
+                        projection_dir: argumentValue(command_args, '--work-dir') ?? undefined
+                    });
+                    const association = await rebindRepositoryConfig({
+                        repository_root: git.repository_root,
+                        expected_repository_id: expected_project_id,
+                        repository_id: project_id,
+                        sidecar_dir: environment.sidecar_dir
+                    });
+                    const binding = store.bindBranch({
+                        source_ref: git.ref,
+                        branch_id,
+                        worktree_id: ensured.worktree.id
+                    });
+                    printJson({
+                        reconnected: true,
+                        association,
+                        binding,
+                        worktree: ensured.worktree,
+                        status
+                    });
+                    return;
+                }
+                if (command === 'context') {
+                    const projection_state = branch_binding
+                        ? store.getProjectionState(branch_binding.worktree_id)
+                        : null;
+                    printJson({
+                        source: git,
+                        sdlc: {
+                            environment_profile: environment.profile,
+                            environment_sidecar_dir: environment.sidecar_dir,
+                            environment_connection: environment.connection
+                                ? trustedConnectionSummary(environment.connection)
+                                : null,
+                            legacy_migration_required: environment.legacy_migration_required,
+                            repository_id: config.repository_id,
+                            state_dir,
+                            state_dir_source: state_resolution.source,
+                            state_warning: state_resolution.warning,
+                            branch_binding,
+                            projection_state
+                        }
+                    });
+                    return;
+                }
+                if (command === 'branches') {
+                    printJson(await branchesCommand({
+                        args: command_args,
+                        client: resolveClient([], environment),
+                        project_id: config.repository_id,
+                        bound_branch_id: branch_binding?.branch_id ?? null,
+                        source_ref: git.ref
+                    }));
+                    return;
+                }
+                if (command === 'branch' && subcommand === 'bind') {
+                    if (!git.ref) {
+                        throw new Error('Detached HEAD cannot be bound to an SDLC branch.');
+                    }
+                    const branch_id = requiredArgument(rest, '--branch-id');
+                    const requested_worktree_id = argumentValue(rest, '--worktree-id');
+                    let worktree_id = requested_worktree_id;
+                    let worktree = null;
+                    if (!worktree_id) {
+                        const ensured = await ensureBranchWorktree(resolveClient(command_args, environment), branch_id);
+                        if (ensured.branch_id !== branch_id ||
+                            ensured.project_id !== config.repository_id) {
+                            throw new Error('Initialized worktree does not belong to the active project and requested branch.');
+                        }
+                        worktree_id = ensured.worktree.id;
+                        worktree = ensured.worktree;
+                    }
+                    const binding = store.bindBranch({
+                        source_ref: git.ref,
+                        branch_id,
+                        worktree_id
+                    });
+                    printJson({ binding, worktree });
+                    return;
+                }
+                const local_workspace = branch_binding
+                    ? {
+                        worktree_id: branch_binding.worktree_id,
+                        revision: store.getActiveSession(branch_binding.worktree_id)
+                            ?.last_acknowledged_revision ?? null
+                    }
+                    : null;
+                if (command === 'branch' && subcommand === 'apply') {
+                    const result = await branchApplyCommand({
+                        args: rest,
+                        client: resolveClient([], environment),
+                        bound_branch_id: branch_binding?.branch_id ?? null,
+                        project_id: config.repository_id,
+                        local_workspace
+                    });
+                    printJson(result.output);
+                    if (result.exit_code !== 0)
+                        process.exitCode = result.exit_code;
+                    return;
+                }
+                if (command === 'branch' && subcommand === 'commit') {
+                    const result = await branchCommitCommand({
+                        args: rest,
+                        client: resolveClient([], environment),
+                        bound_branch_id: branch_binding?.branch_id ?? null,
+                        project_id: config.repository_id,
+                        local_workspace
+                    });
+                    printJson(result.output);
+                    if (result.exit_code !== 0)
+                        process.exitCode = result.exit_code;
+                    return;
+                }
+                if (command === 'session' && subcommand === 'start') {
+                    const binding = requireBinding(branch_binding);
+                    const requested_worktree_id = argumentValue(rest, '--worktree-id');
+                    if (requested_worktree_id &&
+                        requested_worktree_id !== binding.worktree_id) {
+                        throw new Error('Requested worktree does not match the current branch binding.');
+                    }
+                    const revision = Number(requiredArgument(rest, '--revision'));
+                    const session = store.startSession({
+                        worktree_id: binding.worktree_id,
+                        revision
+                    });
+                    printJson({ session });
+                    return;
+                }
+                if (command === 'checkout' || command === 'refresh') {
+                    if (!git.ref) {
+                        throw new Error('Detached HEAD is read-only for SDLC materialization.');
+                    }
+                    const binding = requireBinding(branch_binding);
+                    const operation = command === 'checkout'
+                        ? checkoutWorktreeProjection
+                        : refreshWorktreeProjection;
+                    const status = await operation({
+                        store,
+                        client: resolveClient(command_args, environment),
+                        worktree_id: binding.worktree_id,
+                        repository_root: git.repository_root,
+                        projection_dir: argumentValue(command_args, '--work-dir') ?? undefined,
+                        force: hasArgument(command_args, '--force'),
+                        upgrade_evidence: hasArgument(command_args, '--upgrade-evidence')
+                    });
+                    printJson({ operation: command, status });
+                    return;
+                }
+                if (command === 'status' ||
+                    command === 'diff' ||
+                    command === 'validate') {
+                    const binding = branch_binding;
+                    const requested_worktree_id = argumentValue(command_args, '--worktree-id');
+                    const worktree_id = requested_worktree_id ?? binding?.worktree_id ?? null;
+                    const projection_status = worktree_id
+                        ? await getManagedProjectionStatus({ store, worktree_id })
+                        : null;
+                    if ((command === 'diff' || command === 'validate') &&
+                        !projection_status?.materialized) {
+                        throw new Error('No managed projection exists. Run sdlc checkout first.');
+                    }
+                    if (command === 'diff') {
+                        printJson({ worktree_id, diff: projection_status?.diff });
+                        return;
+                    }
+                    if (command === 'validate') {
+                        const missing_unrecorded = projection_status?.diff?.missing_unrecorded ?? [];
+                        const valid = projection_status?.validation?.is_valid === true &&
+                            missing_unrecorded.length === 0;
+                        printJson({
+                            worktree_id,
+                            valid,
+                            validation: projection_status?.validation,
+                            missing_unrecorded
+                        });
+                        if (!valid)
+                            process.exitCode = 2;
+                        return;
+                    }
+                    printJson({
+                        environment_profile: environment.profile,
+                        repository_id: config.repository_id,
+                        source_ref: git.ref,
+                        source_head: git.head,
+                        source_dirty: git.is_dirty,
+                        state_dir,
+                        branch_binding,
+                        active_session: worktree_id
+                            ? store.getActiveSession(worktree_id)
+                            : null,
+                        projection: projection_status
+                    });
+                    return;
+                }
+                if (command === 'compare') {
+                    const binding = requireBinding(branch_binding);
+                    const projection_state = store.getProjectionState(binding.worktree_id);
+                    if (!projection_state) {
+                        throw new Error('No managed projection exists. Run sdlc checkout first.');
+                    }
+                    const composed = await composeGraphProjection(projection_state.projection_dir);
+                    const options = {
+                        scope_recipes: await readAutoMergeScopeRecipes(argumentValue(command_args, '--scope-recipes-file')),
+                        include_entities: hasArgument(command_args, '--include-entities'),
+                        include_fields: !hasArgument(command_args, '--no-fields'),
+                        entity_ids: command_args
+                            .filter((value) => value.startsWith('--entity-id='))
+                            .map((value) => value.slice('--entity-id='.length))
+                    };
+                    const target_graph_file = argumentValue(command_args, '--target-graph-file');
+                    const source_graph_file = argumentValue(command_args, '--source-graph-file');
+                    const merge_graph_file = argumentValue(command_args, '--merge-base-graph-file');
+                    if (source_graph_file && !target_graph_file) {
+                        throw new Error('--source-graph-file requires --target-graph-file. Without an explicit target, compare uses the managed projection against the bound saved branch.');
+                    }
+                    const response = target_graph_file
+                        ? await compareGraphPayloads(resolveClient(command_args, environment), {
+                            target_graph: await readPortableGraphFile(target_graph_file),
+                            source_graph: source_graph_file
+                                ? await readPortableGraphFile(source_graph_file)
+                                : composed.graph,
+                            merge_graph: merge_graph_file
+                                ? await readPortableGraphFile(merge_graph_file)
+                                : undefined,
+                            labels: {
+                                target: 'Explicit Target Graph',
+                                source: source_graph_file
+                                    ? 'Explicit Source Graph'
+                                    : 'Managed Local Projection',
+                                merge: merge_graph_file
+                                    ? 'Explicit Merge Base Graph'
+                                    : 'Target Fallback'
+                            },
+                            options
+                        })
+                        : await compareGraphWorkspace(resolveClient(command_args, environment), {
+                            branch_id: binding.branch_id,
+                            source: 'local_graph',
+                            graph: composed.graph,
+                            options
+                        });
+                    printJson(response);
+                    if (hasArgument(command_args, '--require-auto-merge-clean') &&
+                        !isAutoMergePreflightClean(response.auto_merge_simulation)) {
+                        process.exitCode = 2;
+                    }
+                    return;
+                }
+                if (command === 'scope-impact') {
+                    const binding = requireBinding(branch_binding);
+                    const projection_state = store.getProjectionState(binding.worktree_id);
+                    if (!projection_state) {
+                        throw new Error('No managed projection exists. Run sdlc checkout first.');
+                    }
+                    const impact_node_id = argumentValue(command_args, '--impact-node-id');
+                    const impact_edge_id = argumentValue(command_args, '--impact-edge-id');
+                    if (Boolean(impact_node_id) === Boolean(impact_edge_id)) {
+                        throw new Error('Provide exactly one --impact-node-id or --impact-edge-id.');
+                    }
+                    await requireManagedProjectionCompleteness({
+                        store,
+                        worktree_id: binding.worktree_id
+                    });
+                    const composed = await composeGraphProjection(projection_state.projection_dir);
+                    const result = resolveLocalScopeImpact({
+                        graph: composed.graph,
+                        selectors: {
+                            path_ids: argumentValues(command_args, '--path-id'),
+                            path_tree_root_ids: argumentValues(command_args, '--path-tree-root-id'),
+                            node_ids: argumentValues(command_args, '--node-id'),
+                            edge_ids: argumentValues(command_args, '--edge-id')
+                        },
+                        entity: impact_node_id
+                            ? { entity_kind: 'node', entity_id: impact_node_id }
+                            : {
+                                entity_kind: 'edge',
+                                entity_id: impact_edge_id
+                            }
+                    });
+                    if (result.status === 'invalid_projection') {
+                        printJson({
+                            operation: 'scope-impact',
+                            source: 'managed_local_projection',
+                            status: 'invalid_projection',
+                            validation: result.validation
+                        });
+                        process.exitCode = 2;
+                        return;
+                    }
+                    if (result.status === 'resolution_failed') {
+                        printJson({
+                            operation: 'scope-impact',
+                            source: 'managed_local_projection',
+                            resolution: result.resolution
+                        });
+                        process.exitCode = 2;
+                        return;
+                    }
+                    printJson({
+                        operation: 'scope-impact',
+                        source: 'managed_local_projection',
+                        recipe_hash: result.recipe_hash,
+                        membership_profile_id: result.membership_profile_id,
+                        membership_profile_version: result.membership_profile_version,
+                        impact: result.impact
+                    });
+                    return;
+                }
+                if (command === 'compare-subgraph') {
+                    const binding = requireBinding(branch_binding);
+                    const projection_state = store.getProjectionState(binding.worktree_id);
+                    const session = store.getActiveSession(binding.worktree_id);
+                    if (!projection_state || !session) {
+                        throw new Error('A managed projection and active session are required. Run sdlc checkout first.');
+                    }
+                    if (!session.last_acknowledged_sync_root_hash) {
+                        throw new Error('The active session has no acknowledged sync root. Run sdlc sync or checkout first.');
+                    }
+                    const seed_entity_ids = argumentValues(command_args, '--seed-entity-id');
+                    if (seed_entity_ids.length === 0) {
+                        throw new Error('Provide at least one --seed-entity-id <node-or-edge-or-path-id>.');
+                    }
+                    const target = explicitGraphTarget(command_args, 'target') ?? {
+                        branch_id: binding.branch_id
+                    };
+                    const source = explicitGraphTarget(command_args, 'source') ?? {
+                        worktree_id: binding.worktree_id,
+                        worktree_revision: session.last_acknowledged_revision,
+                        worktree_root_hash: session.last_acknowledged_sync_root_hash
+                    };
+                    const connection_hops = optionalIntegerArgument({
+                        args: command_args,
+                        name: '--connection-hops',
+                        min: 0,
+                        max: 3
+                    });
+                    const related_path_hops = optionalIntegerArgument({
+                        args: command_args,
+                        name: '--related-path-hops',
+                        min: 0,
+                        max: 1
+                    });
+                    const connection_direction = argumentValue(command_args, '--connection-direction');
+                    if (connection_direction &&
+                        !['incoming', 'outgoing', 'both'].includes(connection_direction)) {
+                        throw new Error('--connection-direction must be incoming, outgoing, or both.');
+                    }
+                    const descendants = argumentValue(command_args, '--descendants');
+                    if (descendants && !['none', 'direct', 'all'].includes(descendants)) {
+                        throw new Error('--descendants must be none, direct, or all.');
+                    }
+                    const projection_overridden = [
+                        connection_hops,
+                        related_path_hops,
+                        connection_direction,
+                        descendants
+                    ].some((value) => value !== undefined && value !== null) ||
+                        hasArgument(command_args, '--no-intersecting-paths') ||
+                        hasArgument(command_args, '--no-internal-edges');
+                    const projection = projection_overridden
+                        ? {
+                            ...(connection_hops !== undefined ? { connection_hops } : {}),
+                            ...(related_path_hops !== undefined
+                                ? { related_path_hops }
+                                : {}),
+                            ...(connection_direction ? { connection_direction } : {}),
+                            ...(descendants ? { descendants } : {}),
+                            ...(hasArgument(command_args, '--no-intersecting-paths')
+                                ? { include_intersecting_paths: false }
+                                : {}),
+                            ...(hasArgument(command_args, '--no-internal-edges')
+                                ? { include_internal_edges: false }
+                                : {})
+                        }
+                        : undefined;
+                    const response = await compareGraphSubgraphs(resolveClient(command_args, environment), {
+                        target,
+                        source,
+                        seed_entity_ids,
+                        ...(projection ? { projection } : {}),
+                        max_nodes: optionalIntegerArgument({
+                            args: command_args,
+                            name: '--max-nodes',
+                            min: 1,
+                            max: 240
+                        }),
+                        max_edges: optionalIntegerArgument({
+                            args: command_args,
+                            name: '--max-edges',
+                            min: 0,
+                            max: 480
+                        }),
+                        max_paths: optionalIntegerArgument({
+                            args: command_args,
+                            name: '--max-paths',
+                            min: 0,
+                            max: 240
+                        }),
+                        max_path_relations: optionalIntegerArgument({
+                            args: command_args,
+                            name: '--max-path-relations',
+                            min: 0,
+                            max: 240
+                        })
+                    });
+                    printJson(response);
+                    if (hasArgument(command_args, '--require-unchanged') &&
+                        response.status !== 'unchanged') {
+                        process.exitCode = 2;
+                    }
+                    return;
+                }
+                if (command === 'rebuild') {
+                    const binding = requireBinding(branch_binding);
+                    if (!git.ref) {
+                        throw new Error('Detached HEAD is read-only for SDLC rebuilds.');
+                    }
+                    const response = await rebuildCommand({
+                        store,
+                        client: resolveClient(command_args, environment),
+                        worktree_id: binding.worktree_id,
+                        node_ids: argumentValues(command_args, '--node'),
+                        without_projection: hasArgument(command_args, '--without-projection')
+                    });
+                    printJson(response);
+                    if (!response.accepted)
+                        process.exitCode = 2;
+                    return;
+                }
+                if (command === 'reset') {
+                    const binding = requireBinding(branch_binding);
+                    if (!git.ref) {
+                        throw new Error('Detached HEAD is read-only for SDLC resets.');
+                    }
+                    printJson(await resetCommand({
+                        store,
+                        client: resolveClient(command_args, environment),
+                        worktree_id: binding.worktree_id,
+                        discard_proposal: hasArgument(command_args, '--discard-proposal')
+                    }));
+                    return;
+                }
+                if (command === 'rm') {
+                    const binding = requireBinding(branch_binding);
+                    if (!subcommand || subcommand.startsWith('--')) {
+                        throw new Error('Usage: sdlc rm <entity-relative-path>');
+                    }
+                    const result = await removeManagedProjectionEntity({
+                        store,
+                        worktree_id: binding.worktree_id,
+                        relative_path: subcommand
+                    });
+                    printJson(result);
+                    return;
+                }
+                if (command === 'media' && subcommand === 'upload') {
+                    const binding = requireBinding(branch_binding);
+                    const file_path = rest.find((argument, index) => !argument.startsWith('--') && rest[index - 1] !== '--timeout-ms');
+                    if (!file_path) {
+                        throw new Error('Usage: sdlc media upload <image-path>');
+                    }
+                    const response = await uploadHostedWorktreeMedia(resolveClient(command_args, environment), binding.worktree_id, {
+                        bytes: await readFile(file_path, {
+                            signal: currentOperation()?.signal
+                        }),
+                        filename: basename(file_path),
+                        mime_type: imageMimeFromPath(file_path)
+                    });
+                    printJson(response);
+                    return;
+                }
+                if (command === 'save') {
+                    const binding = requireBinding(branch_binding);
+                    if (!git.ref) {
+                        throw new Error('Detached HEAD is read-only for SDLC live saves.');
+                    }
+                    const requested_worktree_id = argumentValue(command_args, '--worktree-id');
+                    if (requested_worktree_id &&
+                        requested_worktree_id !== binding.worktree_id) {
+                        throw new Error('Requested worktree does not match the current branch binding.');
+                    }
+                    const client = resolveClient(command_args, environment);
+                    const source_context = {
+                        repository_id: config.repository_id,
+                        git_ref: git.ref,
+                        git_commit: git.head,
+                        is_dirty: git.is_dirty
+                    };
+                    const graph_file = argumentValue(command_args, '--graph-file');
+                    // Standard output carries only the JSON result.
+                    const progress = (message) => {
+                        process.stderr.write(`${message}\n`);
+                    };
+                    if (!graph_file) {
+                        const result = await saveManagedProjection({
+                            store,
+                            client,
+                            worktree_id: binding.worktree_id,
+                            source_context,
+                            progress
+                        });
+                        printJson(result);
+                        if (result.saved && !result.result.response.accepted)
+                            process.exitCode = 2;
+                        return;
+                    }
+                    const session = store.getActiveSession(binding.worktree_id);
+                    if (!session) {
+                        throw new Error('Start a local session for this worktree before saving.');
+                    }
+                    const result = await saveLiveWorktreeChange({
+                        store,
+                        client,
+                        worktree_id: binding.worktree_id,
+                        session_id: session.id,
+                        graph: parsePortableGraph(await readFile(graph_file, 'utf8')),
+                        source_context,
+                        save_mode: parseGraphFileSaveMode(argumentValue(command_args, '--save-mode')),
+                        progress
+                    });
+                    printJson(result);
+                    if (!result.response.accepted)
+                        process.exitCode = 2;
+                    return;
+                }
+                if (command === 'sync') {
+                    const binding = requireBinding(branch_binding);
+                    const client = resolveClient(command_args, environment);
+                    const session = store.getActiveSession(binding.worktree_id);
+                    if (!session) {
+                        throw new Error('No active local session exists for this worktree.');
+                    }
+                    const pending = store.listPendingChanges(session.id)[0];
+                    if (pending)
+                        trackPendingOperation(pending, true);
+                    if (hasArgument(command_args, '--recover-stale-pending')) {
+                        const expected_remote_revision = Number(requiredArgument(command_args, '--expected-remote-revision'));
+                        const expected_remote_sync_revision = Number(requiredArgument(command_args, '--expected-remote-sync-revision'));
+                        const expected_remote_sync_root_hash = requiredArgument(command_args, '--expected-remote-sync-root-hash');
+                        const result = await recoverManagedProjectionFromStalePending({
+                            store,
+                            client,
+                            worktree_id: binding.worktree_id,
+                            expected_remote_revision,
+                            expected_remote_sync_revision,
+                            expected_remote_sync_root_hash,
+                            allow_unapplied_remote_state: hasArgument(command_args, '--discard-unapplied-pending')
+                        });
+                        printJson(result);
+                        return;
+                    }
+                    const result = store.getProjectionState(binding.worktree_id)
+                        ? await syncManagedProjection({
+                            store,
+                            client,
+                            worktree_id: binding.worktree_id,
+                            session_id: session.id
+                        })
+                        : await syncPendingWorktreeChanges({
+                            store,
+                            client,
+                            worktree_id: binding.worktree_id,
+                            session_id: session.id
+                        });
+                    printJson(result);
+                    const conflicts = 'conflicts' in result ? result.conflicts : result.result.conflicts;
+                    if (conflicts.length > 0)
+                        process.exitCode = 2;
+                    return;
+                }
+                throw new Error(SDLC_CLI_USAGE);
+            }
+            finally {
+                store.close();
+            }
+        }
+    });
+}
+void runCliOperation(process.argv.slice(2), main).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    // A save the server still finalizes in the background exits with its own
+    // status, so a caller can tell it from a failure and run sdlc sync.
+    process.exitCode =
+        error instanceof TreeSaveStillFinalizingError ? error.exit_code : 1;
+});
+//# sourceMappingURL=cli.js.map