@tiangong-lca/cli 0.0.19 → 0.0.22

package/dist/src/cli.js

@@ -54,6 +54,10 @@ import { runDatasetPatchApply, } from './lib/dataset-patch.js';
 import { runDatasetSaveDraft, } from './lib/dataset-save-draft-run.js';
 import { runDatasetClassificationApply, runDatasetClassificationAudit, runDatasetClassificationChildren, runDatasetClassificationPath, } from './lib/dataset-classification.js';
 import { runDatasetMaintenanceClearAccount, } from './lib/dataset-maintenance-clear-account.js';
+import { runDatasetMaintenancePlan } from './lib/dataset-maintenance-plan.js';
+import { runDatasetMaintenanceApply } from './lib/dataset-maintenance-apply.js';
+import { runDatasetMaintenanceVerify } from './lib/dataset-maintenance-verify.js';
+import { runDatasetSourceUploadAttachments, } from './lib/dataset-source-upload-attachments.js';
 function renderMainHelp(dotEnvStatus) {
     return `TianGong LCA CLI
 
@@ -73,7 +77,7 @@ Implemented Commands:
   doctor     show environment diagnostics
   search     flow | process | lifecyclemodel
   process    get | list | identity-preflight | build-plan | scope-statistics | dedup-review | auto-build | resume-build | publish-build | complete-required-fields | save-draft | batch-build | refresh-references | verify-rows
-  dataset    contract get | context-pack | classification children/path/audit/apply | curation-queue build/next/verify | import-lca convert | author | patch apply | save-draft | validate | verify-remote | bilingual extract/apply/validate | evidence-search plan/run | references rewrite/refresh-remote | maintenance clear-account
+  dataset    contract get | context-pack | classification children/path/audit/apply | curation-queue build/next/verify | import-lca convert | author | patch apply | save-draft | source upload-attachments | validate | verify-remote | bilingual extract/apply/validate | evidence-search plan/run | references rewrite/refresh-remote | maintenance clear-account/plan/apply/verify
   flow       get | list | identity-preflight | build-plan | fetch-rows | materialize-decisions | remediate | publish-version | publish-reviewed-data | build-alias-map | scan-process-flow-refs | plan-process-flow-repairs | apply-process-flow-repairs | regen-product | validate-processes
   lifecyclemodel auto-build | validate-build | publish-build | save-draft | graph | build-resulting-process | publish-resulting-process | orchestrate
   qa         process | flow | lifecyclemodel
@@ -84,7 +88,6 @@ Implemented Commands:
 Planned Surface (not implemented yet):
   auth       whoami | doctor-auth
   job        get | wait | logs
-  dataset maintenance plan | apply | verify
 
 Planned commands currently print an explicit "not implemented yet" message and exit with code 2.
 
@@ -127,7 +130,7 @@ Examples:
   tiangong-lca dataset evidence-search run --input ./evidence-search.request.json --results ./search-results.json --out-dir ./evidence-search
   tiangong-lca dataset references rewrite --input ./rows.jsonl --from flow:<old-id>@<old-version> --to flow:<new-id>@<new-version> --out-dir /abs/path/to/dataset-rewrite
   tiangong-lca dataset maintenance clear-account --out-dir /abs/path/to/account-clear --json
-  tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation redo-import --out-dir /abs/path/to/dataset-maintenance
+  tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation merge-support-aliases --out-dir /abs/path/to/dataset-maintenance
   tiangong-lca lifecyclemodel auto-build --input ./lifecyclemodel-auto-build.request.json --out-dir /abs/path/to/lifecyclemodel-run
   tiangong-lca lifecyclemodel validate-build --run-dir /abs/path/to/lifecyclemodel-run
   tiangong-lca lifecyclemodel publish-build --run-dir /abs/path/to/lifecyclemodel-run
@@ -268,6 +271,7 @@ Implemented Subcommands:
   author              Extract source evidence and prepare TIDAS context packs for AI authoring
   patch apply          Apply AI-authored structured dataset patches deterministically
   save-draft           Save contact/source/support or other canonical dataset rows through the platform dataset command path
+  source upload-attachments Upload source referenceToDigitalFile binaries to storage and rewrite their @uri
   validate             Validate local flow / process / lifecyclemodel rows with the TIDAS SDK
   verify-remote        Verify dataset roots and TIDAS references against remote published versions
   bilingual extract    Extract bilingual translation units from local rows
@@ -277,9 +281,9 @@ Implemented Subcommands:
   references rewrite   Rewrite flow references in local process and lifecyclemodel rows
   references refresh-remote Refresh local TIDAS reference versions to latest reachable remote rows
   maintenance clear-account Dry-run or clear current authenticated account-owned dataset rows through RLS
-
-Planned Subcommands:
-  maintenance plan/apply/verify Plan, execute, and verify RLS-scoped dataset delete/redo maintenance
+  maintenance plan    Build an immutable, RLS-visible row-level maintenance plan
+  maintenance apply   Execute an explicitly approved maintenance plan through current-user RLS
+  maintenance verify  Read back affected rows and references against the immutable plan
 
 Examples:
   tiangong-lca dataset contract get --type process --include schema,methodology,ruleset --out-dir ./contract --help
@@ -305,25 +309,23 @@ Examples:
   tiangong-lca dataset references rewrite --input ./rows.jsonl --from flow:<old-id>@<old-version> --to flow:<new-id>@<new-version> --out-dir ./dataset-rewrite --help
   tiangong-lca dataset references refresh-remote --input ./rows.jsonl --out ./rows.refreshed.jsonl --out-dir ./dataset-reference-refresh --help
   tiangong-lca dataset maintenance clear-account --out-dir ./account-clear --json --help
-  tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation redo-import --out-dir ./dataset-maintenance --help
+  tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation merge-support-aliases --out-dir ./dataset-maintenance --help
 `.trim();
 }
 function renderDatasetMaintenanceHelp() {
     return `Usage:
   tiangong-lca dataset maintenance <clear-account|plan|apply|verify> [options]
 
-Status:
-  clear-account is implemented for current authenticated account cleanup.
-  plan/apply/verify remain reserved for row-level RLS-scoped cleanup and redo workflows and currently exit with code 2 for executable actions.
-
-Implemented Actions:
+Actions:
   clear-account Dry-run or delete current authenticated account-owned lifecyclemodels, processes, flows, sources, and contacts.
-
-Planned Actions:
   plan    Build an immutable maintenance plan from a scope manifest, visible remote snapshot, dependency impact report, and intended operation.
   apply   Execute an approved plan through current-user RLS and platform dataset command paths; never bypass RLS or delete rows outside the visible scope.
   verify  Re-fetch affected rows and references, then prove that deleted, updated, skipped, protected, and redone rows match the plan.
 
+Safety:
+  plan and verify are read-only.
+  apply is commit-only and requires --commit, the exact plan SHA-256 via --approve-plan, and the current account email via --confirm.
+
 Required Artifact Contract:
   - maintenance-plan.json
   - rls-visible-snapshot.json
@@ -336,11 +338,66 @@ Required Artifact Contract:
 Examples:
   tiangong-lca dataset maintenance clear-account --out-dir ./account-clear --json
   tiangong-lca dataset maintenance clear-account --commit --confirm user@example.com --out-dir ./account-clear
-  tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation redo-import --out-dir ./dataset-maintenance
-  tiangong-lca dataset maintenance apply --plan ./dataset-maintenance/maintenance-plan.json --commit
+  tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation merge-support-aliases --out-dir ./dataset-maintenance
+  tiangong-lca dataset maintenance apply --plan ./dataset-maintenance/maintenance-plan.json --commit --approve-plan <sha256> --confirm user@example.com
   tiangong-lca dataset maintenance verify --plan ./dataset-maintenance/maintenance-plan.json --out-dir ./dataset-maintenance/verify
 `.trim();
 }
+function renderDatasetMaintenancePlanHelp() {
+    return `Usage:
+  tiangong-lca dataset maintenance plan --scope <file> --operation <operation> --out-dir <dir> [options]
+
+Operations:
+  delete | retire | redo-import | repair-references | merge-support-aliases
+
+Options:
+  --scope <file>       Maintenance scope manifest
+  --operation <value> Intended row-level maintenance operation
+  --out-dir <dir>      Artifact directory
+  --page-size <n>      Snapshot page size
+  --timeout-ms <n>     Request timeout in milliseconds
+  --json               Print compact JSON
+  -h, --help
+
+Outputs written under --out-dir include the immutable maintenance-plan.json, visible snapshot,
+protected-row ledger, reference-impact report, and dry-run report.
+`.trim();
+}
+function renderDatasetMaintenanceApplyHelp() {
+    return `Usage:
+  tiangong-lca dataset maintenance apply --plan <file> --commit --approve-plan <sha256> --confirm <email> [options]
+
+Behavior:
+  Commit-only. The command rejects dry-run mode, a missing --commit flag, a plan hash mismatch,
+  or a confirmation email that does not match the current authenticated account.
+
+Options:
+  --plan <file>          Immutable maintenance-plan.json
+  --commit               Execute the approved plan
+  --approve-plan <sha256> Exact SHA-256 recorded for the plan
+  --confirm <email>      Current authenticated account email
+  --timeout-ms <n>       Request timeout in milliseconds
+  --json                 Print compact JSON
+  -h, --help
+
+Outputs include approval-record.json and commit-report.json alongside an append-only action ledger.
+`.trim();
+}
+function renderDatasetMaintenanceVerifyHelp() {
+    return `Usage:
+  tiangong-lca dataset maintenance verify --plan <file> [options]
+
+Options:
+  --plan <file>       Immutable maintenance-plan.json
+  --out-dir <dir>     Optional verification artifact directory
+  --page-size <n>     Readback page size
+  --timeout-ms <n>    Request timeout in milliseconds
+  --json              Print compact JSON
+  -h, --help
+
+Outputs include readback-verify-report.json with affected-row and reference checks.
+`.trim();
+}
 function renderDatasetMaintenanceClearAccountHelp() {
     return `Usage:
   tiangong-lca dataset maintenance clear-account [options]
@@ -518,7 +575,7 @@ function renderDatasetImportLcaHelp() {
 Options:
   --input <path>          Source file, directory, or package to import
   --output-dir <dir>      Output directory for generated package and reports
-  --from-format <format>  auto, ecospold1, ecospold2, openlca-jsonld, openlca-process-xlsx, simapro-csv
+  --from-format <format>  auto, ecospold1, ecospold2, openlca-jsonld, openlca-process-xlsx, simapro-csv, ilcd
   --target <target>       tidas | ilcd | both (default: tidas)
   --report <file>         Conversion report path (default: <output-dir>/conversion-report.json)
   --mapping-dir <dir>     Optional custom mapping/reference data directory
@@ -644,6 +701,33 @@ Contract:
   Process and lifecyclemodel imports may still use their dedicated save-draft commands when the workflow needs their specialized reports.
 `.trim();
 }
+function renderDatasetSourceUploadAttachmentsHelp() {
+    return `Usage:
+  tiangong-lca dataset source upload-attachments --input <file|dir> --external-docs-dir <dir> [options]
+
+Uploads the binary documents referenced by source datasets via referenceToDigitalFile
+(e.g. "../external_docs/pef_method.pdf") to a Supabase Storage bucket using the current
+authenticated account session, then rewrites each source's referenceToDigitalFile @uri to
+"../<bucket>/<key>". Plain http(s) URIs are left untouched; backslash paths and filename
+case differences are normalized; each physical file is uploaded once (deduped).
+
+Options:
+  --input <file|dir>        Source TIDAS rows (.jsonl, .json, or a directory of *.json)
+  --external-docs-dir <dir> Directory holding the referenced binaries
+  --bucket <name>           Storage bucket (default: external_docs)
+  --out-dir <dir>           Artifact directory
+  --commit                  Upload binaries (default: dry-run plan only)
+  --dry-run                 Plan without uploading (default)
+  --verify                  After upload, create a signed URL to confirm each object resolves
+  --timeout-ms <n>          Per-request timeout (default: 30000)
+  --json                    Print compact JSON
+  -h, --help
+
+Outputs written under --out-dir:
+  - attachments-report.json
+  - rewritten-sources.jsonl
+`.trim();
+}
 function renderDatasetValidateHelp() {
     return `Usage:
   tiangong-lca dataset validate --input <file> [options]
@@ -2096,6 +2180,62 @@ function parseDatasetSaveDraftFlags(args) {
         allowReferenceOnlySupport: Boolean(values['allow-account-local-support']),
     };
 }
+function parseDatasetSourceUploadAttachmentsFlags(args) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args,
+            allowPositionals: false,
+            strict: true,
+            options: {
+                help: { type: 'boolean', short: 'h' },
+                json: { type: 'boolean' },
+                input: { type: 'string' },
+                'external-docs-dir': { type: 'string' },
+                bucket: { type: 'string' },
+                'out-dir': { type: 'string' },
+                commit: { type: 'boolean' },
+                'dry-run': { type: 'boolean' },
+                verify: { type: 'boolean' },
+                'timeout-ms': { type: 'string' },
+            },
+        }));
+    }
+    catch (error) {
+        throw new CliError(String(error), {
+            code: 'INVALID_ARGS',
+            exitCode: 2,
+        });
+    }
+    if (values.commit && values['dry-run']) {
+        throw new CliError('Cannot pass both --commit and --dry-run.', {
+            code: 'INVALID_DATASET_SOURCE_UPLOAD_MODE',
+            exitCode: 2,
+        });
+    }
+    let timeoutMs;
+    if (typeof values['timeout-ms'] === 'string') {
+        const parsed = Number.parseInt(values['timeout-ms'], 10);
+        if (!Number.isInteger(parsed)) {
+            throw new CliError('--timeout-ms must be an integer.', {
+                code: 'INVALID_ARGS',
+                exitCode: 2,
+            });
+        }
+        timeoutMs = parsed;
+    }
+    return {
+        help: Boolean(values.help),
+        json: Boolean(values.json),
+        inputPath: typeof values.input === 'string' ? values.input : '',
+        externalDocsDir: typeof values['external-docs-dir'] === 'string' ? values['external-docs-dir'] : '',
+        bucket: typeof values.bucket === 'string' ? values.bucket : null,
+        outDir: typeof values['out-dir'] === 'string' ? values['out-dir'] : null,
+        commit: Boolean(values.commit),
+        verify: Boolean(values.verify),
+        timeoutMs,
+    };
+}
 function parseDatasetContractFlags(args) {
     let values;
     try {
@@ -2881,6 +3021,130 @@ function parseDatasetMaintenanceClearAccountFlags(args) {
         confirm: typeof values.confirm === 'string' ? values.confirm : null,
     };
 }
+function parseDatasetMaintenancePositiveInteger(value, flagName) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    if (!/^\d+$/u.test(value.trim()) || Number.parseInt(value.trim(), 10) <= 0) {
+        throw new CliError(`${flagName} must be a positive integer.`, {
+            code: 'DATASET_MAINTENANCE_INTEGER_INVALID',
+            exitCode: 2,
+            details: { flag: flagName, value },
+        });
+    }
+    return Number.parseInt(value.trim(), 10);
+}
+function parseDatasetMaintenancePlanFlags(args) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args,
+            allowPositionals: false,
+            strict: true,
+            options: {
+                help: { type: 'boolean', short: 'h' },
+                json: { type: 'boolean' },
+                scope: { type: 'string' },
+                operation: { type: 'string' },
+                'out-dir': { type: 'string' },
+                'page-size': { type: 'string' },
+                'timeout-ms': { type: 'string' },
+            },
+        }));
+    }
+    catch (error) {
+        throw new CliError(String(error), {
+            code: 'INVALID_ARGS',
+            exitCode: 2,
+        });
+    }
+    const rawOperation = typeof values.operation === 'string' ? values.operation : null;
+    if (rawOperation !== null &&
+        !['delete', 'retire', 'redo-import', 'repair-references', 'merge-support-aliases'].includes(rawOperation)) {
+        throw new CliError("--operation must be 'delete', 'retire', 'redo-import', 'repair-references', or 'merge-support-aliases'.", {
+            code: 'DATASET_MAINTENANCE_OPERATION_INVALID',
+            exitCode: 2,
+            details: rawOperation,
+        });
+    }
+    return {
+        help: Boolean(values.help),
+        json: Boolean(values.json),
+        scopePath: typeof values.scope === 'string' ? values.scope : '',
+        operation: rawOperation,
+        outDir: typeof values['out-dir'] === 'string' ? values['out-dir'] : '',
+        pageSize: parseDatasetMaintenancePositiveInteger(values['page-size'], '--page-size'),
+        timeoutMs: parseDatasetMaintenancePositiveInteger(values['timeout-ms'], '--timeout-ms'),
+    };
+}
+function parseDatasetMaintenanceApplyFlags(args) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args,
+            allowPositionals: false,
+            strict: true,
+            options: {
+                help: { type: 'boolean', short: 'h' },
+                json: { type: 'boolean' },
+                plan: { type: 'string' },
+                commit: { type: 'boolean' },
+                'approve-plan': { type: 'string' },
+                confirm: { type: 'string' },
+                'timeout-ms': { type: 'string' },
+                'dry-run': { type: 'boolean' },
+            },
+        }));
+    }
+    catch (error) {
+        throw new CliError(String(error), {
+            code: 'INVALID_ARGS',
+            exitCode: 2,
+        });
+    }
+    return {
+        help: Boolean(values.help),
+        json: Boolean(values.json),
+        planPath: typeof values.plan === 'string' ? values.plan : '',
+        commit: Boolean(values.commit),
+        approvePlan: typeof values['approve-plan'] === 'string' ? values['approve-plan'] : '',
+        confirm: typeof values.confirm === 'string' ? values.confirm : '',
+        timeoutMs: parseDatasetMaintenancePositiveInteger(values['timeout-ms'], '--timeout-ms'),
+        dryRun: Boolean(values['dry-run']),
+    };
+}
+function parseDatasetMaintenanceVerifyFlags(args) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args,
+            allowPositionals: false,
+            strict: true,
+            options: {
+                help: { type: 'boolean', short: 'h' },
+                json: { type: 'boolean' },
+                plan: { type: 'string' },
+                'out-dir': { type: 'string' },
+                'page-size': { type: 'string' },
+                'timeout-ms': { type: 'string' },
+            },
+        }));
+    }
+    catch (error) {
+        throw new CliError(String(error), {
+            code: 'INVALID_ARGS',
+            exitCode: 2,
+        });
+    }
+    return {
+        help: Boolean(values.help),
+        json: Boolean(values.json),
+        planPath: typeof values.plan === 'string' ? values.plan : '',
+        outDir: typeof values['out-dir'] === 'string' ? values['out-dir'] : undefined,
+        pageSize: parseDatasetMaintenancePositiveInteger(values['page-size'], '--page-size'),
+        timeoutMs: parseDatasetMaintenancePositiveInteger(values['timeout-ms'], '--timeout-ms'),
+    };
+}
 function parseIdentityPreflightFlags(args) {
     let values;
     try {
@@ -4626,6 +4890,10 @@ export async function executeCli(argv, deps) {
         const datasetClassificationAuditImpl = deps.runDatasetClassificationAuditImpl ?? runDatasetClassificationAudit;
         const datasetClassificationApplyImpl = deps.runDatasetClassificationApplyImpl ?? runDatasetClassificationApply;
         const datasetMaintenanceClearAccountImpl = deps.runDatasetMaintenanceClearAccountImpl ?? runDatasetMaintenanceClearAccount;
+        const datasetMaintenancePlanImpl = deps.runDatasetMaintenancePlanImpl ?? runDatasetMaintenancePlan;
+        const datasetMaintenanceApplyImpl = deps.runDatasetMaintenanceApplyImpl ?? runDatasetMaintenanceApply;
+        const datasetMaintenanceVerifyImpl = deps.runDatasetMaintenanceVerifyImpl ?? runDatasetMaintenanceVerify;
+        const datasetSourceUploadAttachmentsImpl = deps.runDatasetSourceUploadAttachmentsImpl ?? runDatasetSourceUploadAttachments;
         if (flags.version) {
             return { exitCode: 0, stdout: `${loadCliPackageVersion(import.meta.url)}\n`, stderr: '' };
         }
@@ -4947,6 +5215,58 @@ export async function executeCli(argv, deps) {
                 stderr: '',
             };
         }
+        if (command === 'dataset' && subcommand === 'source') {
+            const action = commandArgs[0] ?? '';
+            if (!action || action === '--help' || action === '-h') {
+                return {
+                    exitCode: 0,
+                    stdout: `${renderDatasetSourceUploadAttachmentsHelp()}\n`,
+                    stderr: '',
+                };
+            }
+            if (action !== 'upload-attachments') {
+                throw new CliError("dataset source action must be 'upload-attachments'.", {
+                    code: 'DATASET_SOURCE_ACTION_INVALID',
+                    exitCode: 2,
+                });
+            }
+            const datasetFlags = parseDatasetSourceUploadAttachmentsFlags(commandArgs.slice(1));
+            if (datasetFlags.help) {
+                return {
+                    exitCode: 0,
+                    stdout: `${renderDatasetSourceUploadAttachmentsHelp()}\n`,
+                    stderr: '',
+                };
+            }
+            if (!datasetFlags.inputPath) {
+                throw new CliError('dataset source upload-attachments requires --input.', {
+                    code: 'DATASET_SOURCE_UPLOAD_INPUT_REQUIRED',
+                    exitCode: 2,
+                });
+            }
+            if (!datasetFlags.externalDocsDir) {
+                throw new CliError('dataset source upload-attachments requires --external-docs-dir.', {
+                    code: 'DATASET_SOURCE_UPLOAD_EXTERNAL_DOCS_DIR_REQUIRED',
+                    exitCode: 2,
+                });
+            }
+            const report = await datasetSourceUploadAttachmentsImpl({
+                inputPath: datasetFlags.inputPath,
+                externalDocsDir: datasetFlags.externalDocsDir,
+                bucket: datasetFlags.bucket,
+                outDir: datasetFlags.outDir,
+                commit: datasetFlags.commit,
+                verify: datasetFlags.verify,
+                timeoutMs: datasetFlags.timeoutMs,
+                env: deps.env,
+                fetchImpl: deps.fetchImpl,
+            });
+            return {
+                exitCode: report.status === 'completed_with_failures' ? 1 : 0,
+                stdout: stringifyJson(report, datasetFlags.json),
+                stderr: '',
+            };
+        }
         if (command === 'dataset' && subcommand === 'save-draft') {
             const datasetFlags = parseDatasetSaveDraftFlags(commandArgs);
             if (datasetFlags.help) {
@@ -5182,13 +5502,141 @@ export async function executeCli(argv, deps) {
                     stderr: '',
                 };
             }
-            if (!['plan', 'apply', 'verify'].includes(action)) {
-                throw new CliError("dataset maintenance action must be 'clear-account', 'plan', 'apply', or 'verify'.", {
-                    code: 'DATASET_MAINTENANCE_ACTION_INVALID',
-                    exitCode: 2,
+            if (action === 'plan') {
+                const datasetFlags = parseDatasetMaintenancePlanFlags(commandArgs.slice(1));
+                if (datasetFlags.help) {
+                    return {
+                        exitCode: 0,
+                        stdout: `${renderDatasetMaintenancePlanHelp()}\n`,
+                        stderr: '',
+                    };
+                }
+                if (!datasetFlags.scopePath) {
+                    throw new CliError('dataset maintenance plan requires --scope.', {
+                        code: 'DATASET_MAINTENANCE_SCOPE_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.operation) {
+                    throw new CliError('dataset maintenance plan requires --operation.', {
+                        code: 'DATASET_MAINTENANCE_OPERATION_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.outDir) {
+                    throw new CliError('dataset maintenance plan requires --out-dir.', {
+                        code: 'DATASET_MAINTENANCE_OUT_DIR_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                const report = await datasetMaintenancePlanImpl({
+                    scopePath: datasetFlags.scopePath,
+                    operation: datasetFlags.operation,
+                    outDir: datasetFlags.outDir,
+                    pageSize: datasetFlags.pageSize,
+                    timeoutMs: datasetFlags.timeoutMs,
+                    env: deps.env,
+                    fetchImpl: deps.fetchImpl,
                 });
+                return {
+                    exitCode: report.status === 'blocked' ? 1 : 0,
+                    stdout: stringifyJson(report, datasetFlags.json),
+                    stderr: '',
+                };
             }
-            return plannedCommand('dataset', `maintenance ${action}`);
+            if (action === 'apply') {
+                const datasetFlags = parseDatasetMaintenanceApplyFlags(commandArgs.slice(1));
+                if (datasetFlags.help) {
+                    return {
+                        exitCode: 0,
+                        stdout: `${renderDatasetMaintenanceApplyHelp()}\n`,
+                        stderr: '',
+                    };
+                }
+                if (!datasetFlags.planPath) {
+                    throw new CliError('dataset maintenance apply requires --plan.', {
+                        code: 'DATASET_MAINTENANCE_PLAN_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (datasetFlags.commit && datasetFlags.dryRun) {
+                    throw new CliError('Cannot pass both --commit and --dry-run.', {
+                        code: 'DATASET_MAINTENANCE_APPLY_MODE_CONFLICT',
+                        exitCode: 2,
+                    });
+                }
+                if (datasetFlags.dryRun) {
+                    throw new CliError('dataset maintenance apply is commit-only; use dataset maintenance plan for a dry run.', {
+                        code: 'DATASET_MAINTENANCE_APPLY_COMMIT_ONLY',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.commit) {
+                    throw new CliError('dataset maintenance apply requires --commit.', {
+                        code: 'DATASET_MAINTENANCE_APPLY_COMMIT_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.approvePlan) {
+                    throw new CliError('dataset maintenance apply requires --approve-plan <sha256>.', {
+                        code: 'DATASET_MAINTENANCE_APPROVAL_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.confirm) {
+                    throw new CliError('dataset maintenance apply requires --confirm <email>.', {
+                        code: 'DATASET_MAINTENANCE_CONFIRM_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                const report = await datasetMaintenanceApplyImpl({
+                    planPath: datasetFlags.planPath,
+                    commit: datasetFlags.commit,
+                    approvePlan: datasetFlags.approvePlan,
+                    confirm: datasetFlags.confirm,
+                    timeoutMs: datasetFlags.timeoutMs,
+                    env: deps.env,
+                    fetchImpl: deps.fetchImpl,
+                });
+                return {
+                    exitCode: report.status === 'completed_with_failures' ? 1 : 0,
+                    stdout: stringifyJson(report, datasetFlags.json),
+                    stderr: '',
+                };
+            }
+            if (action === 'verify') {
+                const datasetFlags = parseDatasetMaintenanceVerifyFlags(commandArgs.slice(1));
+                if (datasetFlags.help) {
+                    return {
+                        exitCode: 0,
+                        stdout: `${renderDatasetMaintenanceVerifyHelp()}\n`,
+                        stderr: '',
+                    };
+                }
+                if (!datasetFlags.planPath) {
+                    throw new CliError('dataset maintenance verify requires --plan.', {
+                        code: 'DATASET_MAINTENANCE_PLAN_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                const report = await datasetMaintenanceVerifyImpl({
+                    planPath: datasetFlags.planPath,
+                    outDir: datasetFlags.outDir,
+                    pageSize: datasetFlags.pageSize,
+                    timeoutMs: datasetFlags.timeoutMs,
+                    env: deps.env,
+                    fetchImpl: deps.fetchImpl,
+                });
+                return {
+                    exitCode: report.status === 'failed' ? 1 : 0,
+                    stdout: stringifyJson(report, datasetFlags.json),
+                    stderr: '',
+                };
+            }
+            throw new CliError("dataset maintenance action must be 'clear-account', 'plan', 'apply', or 'verify'.", {
+                code: 'DATASET_MAINTENANCE_ACTION_INVALID',
+                exitCode: 2,
+            });
         }
         if (command === 'lifecyclemodel' && !subcommand) {
             return { exitCode: 0, stdout: `${renderLifecyclemodelHelp()}\n`, stderr: '' };