orizu 0.5.39 → 0.5.41

package/src/dataset-clone-workflow.ts

@@ -0,0 +1,100 @@
+import { Cause, Effect, Exit, Result, Schema } from 'effect'
+
+import { datasetTransferTimeoutMs } from './dataset-transfer-policy.js'
+import { authedFetch } from './http.js'
+import { parseJsonResponse } from './json-response.js'
+
+// Loaded only through `await import(...)` from dataset-commands, like lock.
+
+const SERVER_MAY_BE_CREATED = 'Dataset clone may already be created'
+
+const ClonedDataset = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  rowCount: Schema.Number,
+  parentDatasetId: Schema.String,
+})
+const CloneReply = Schema.Struct({ dataset: ClonedDataset })
+const ErrorReply = Schema.Struct({ error: Schema.String })
+export type ClonedDataset = typeof ClonedDataset.Type
+
+// A refusal means nothing was cloned. After any other failure once the request
+// was sent, the clone may exist. Unlike lock, cloning again is not harmless: it
+// makes another copy, so the clone is never retried and the user is told to look.
+class CloneFailure extends Error {
+  constructor(message: string, readonly mayBeCreated: boolean) { super(message) }
+}
+
+function mayBeCreatedGuidance(name: string | null): string {
+  const target = name ? `a dataset named ${JSON.stringify(name)}` : 'a new dataset named after the source with " Copy" at the end'
+  return `The clone may already have been created. Run \`orizu datasets list\` and look for ${target} before cloning again: running clone again makes another copy.`
+}
+
+// authedFetch raises this code only when it sent nothing, or when the server
+// answered 401 and the changed credentials stopped a replay. Nothing was cloned.
+function isAuthContextChange(cause: unknown): boolean {
+  return cause instanceof Error && cause.message.startsWith('ORIZU_AUTH_CONTEXT_CHANGED:')
+}
+
+function serverError(text: string): string | null {
+  try {
+    const decoded = Schema.decodeUnknownResult(ErrorReply)(JSON.parse(text))
+    return Result.isSuccess(decoded) ? decoded.success.error : null
+  } catch {
+    return null
+  }
+}
+
+function cloneRequest(datasetId: string, name: string | null, timeoutMs: number) {
+  return Effect.suspend(() => {
+    let sent = false
+    let timedOut = false
+    return Effect.tryPromise({
+      try: async signal => {
+        const request = new AbortController()
+        const abort = () => request.abort()
+        const timer = setTimeout(() => { timedOut = true; request.abort() }, timeoutMs)
+        if (signal.aborted) abort()
+        else signal.addEventListener('abort', abort, { once: true })
+        try {
+          const response = await authedFetch(`/api/cli/datasets/${encodeURIComponent(datasetId)}/clone`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(name ? { name } : {}),
+            signal: request.signal,
+          }, () => { sent = true })
+          if (!response.ok) {
+            const text = await response.text()
+            const error = serverError(text)
+            // The app's own 5xx bodies name what happened; anything else at 5xx
+            // (a gateway page, an empty body) says nothing about the clone.
+            const mayBeCreated = response.status < 400 || error === SERVER_MAY_BE_CREATED || (response.status >= 500 && error === null)
+            throw new CloneFailure(`Clone failed: ${text}`, mayBeCreated)
+          }
+          const data = await parseJsonResponse<unknown>(response, 'Dataset clone')
+          const decoded = Schema.decodeUnknownResult(CloneReply)(data)
+          if (Result.isFailure(decoded)) {
+            throw new CloneFailure(`Dataset clone returned an unexpected response (status ${response.status}).`, true)
+          }
+          return decoded.success.dataset
+        } finally {
+          clearTimeout(timer)
+          signal.removeEventListener('abort', abort)
+          request.abort()
+        }
+      },
+      catch: cause => {
+        if (timedOut) return new CloneFailure('DATASET_TRANSFER_TIMEOUT: Dataset clone exceeded its deadline', true)
+        if (cause instanceof CloneFailure) return cause
+        return new CloneFailure(cause instanceof Error ? cause.message : String(cause), sent && !isAuthContextChange(cause))
+      },
+    })
+  }).pipe(Effect.mapError(failure => new Error(failure.mayBeCreated ? `${failure.message}\n${mayBeCreatedGuidance(name)}` : failure.message)))
+}
+
+// Nothing to clean up, so signals keep Node's default handling.
+export async function cloneDataset(datasetId: string, name: string | null): Promise<ClonedDataset> {
+  const exit = await Effect.runPromiseExit(cloneRequest(datasetId, name, datasetTransferTimeoutMs()))
+  if (Exit.isSuccess(exit)) return exit.value
+  throw Cause.squash(exit.cause)
+}

package/src/dataset-commands.ts

@@ -1,11 +1,12 @@
 // ORI-2044: moved from index.ts to keep dataset commands together.
 
-import { readFileSync, writeFileSync } from 'fs'
+import { readFileSync } from 'fs'
 import { basename, extname } from 'path'
 import { createInterface } from 'readline/promises'
 import { stdin as input, stdout as output } from 'process'
 import {
   getArg,
+  hasArg,
   expandHomePath,
   getPositionalArg,
   hasJsonFlag,
@@ -21,14 +22,12 @@ import {
 } from './account-directory.js'
 import { sanitizeTerminalText, parseJsonResponse } from './json-response.js'
 import { authedFetch } from './http.js'
-import { extractErrorMessage } from './error-response.js'
 import { printJson, printLine } from './cli-console-output.js'
 import { readJsonFile } from './app-commands.js'
 import { printDatasetSummaries } from './archive-artifacts-cli.js'
 import { formatTerminalLink } from './auth-commands.js'
 import { parseDatasetFile } from './file-parser.js'
 import { parseDatasetReference } from './dataset-download.js'
-import { editDatasetRows as runEditDatasetRows } from './dataset-edit-rows.js'
 import { parseCommaSeparated } from './task-commands.js'
 import type { DatasetSelection } from './account-directory.js'
 
@@ -36,12 +35,13 @@ import type { DatasetSelection } from './account-directory.js'
 
 const MAX_README_LENGTH = 200_000
 
-interface DatasetVersionResponse {
-  datasetVersion: {
-    id: string
-    rowCount: number
-    artifactFormat?: string
-    artifactStoragePath?: string
+function readReadmeFile(readmeFile: string): string {
+  try {
+    return readFileSync(expandHomePath(readmeFile), 'utf8')
+  } catch (error) {
+    const missing = error instanceof Error && 'code' in error && error.code === 'ENOENT'
+    const reason = missing ? 'file not found' : error instanceof Error ? error.message : String(error)
+    throw new Error(`Could not read README file ${readmeFile}: ${reason}`)
   }
 }
 
@@ -54,7 +54,7 @@ function readReadmeMarkdownFromArgs(usage: string): string | null {
   }
 
   const markdown = readmeFile !== null
-    ? readFileSync(expandHomePath(readmeFile), 'utf8')
+    ? readReadmeFile(readmeFile)
     : readmeText
 
   if (markdown !== null && markdown.length > MAX_README_LENGTH) {
@@ -117,28 +117,6 @@ async function resolveDatasetIdForProject(datasetRef: string, projectArg: string
   return matches[0].id
 }
 
-async function requestDatasetVersionSnapshot(
-  datasetId: string,
-  options: { versionLabel?: string | null; readmeMarkdown?: string | null } = {}
-): Promise<DatasetVersionResponse> {
-  const response = await authedFetch(`/api/cli/datasets/${encodeURIComponent(datasetId)}/versions`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      ...(options.versionLabel ? { versionLabel: options.versionLabel } : {}),
-      ...(options.readmeMarkdown !== undefined && options.readmeMarkdown !== null
-        ? { readmeMarkdown: options.readmeMarkdown }
-        : {}),
-    }),
-  })
-
-  if (!response.ok) {
-    throw new Error(`Failed to create dataset version: ${await extractErrorMessage(response)}`)
-  }
-
-  return parseJsonResponse<DatasetVersionResponse>(response, 'Dataset version create')
-}
-
 async function createDatasetVersion() {
   const datasetId = getPositionalArg(3) || getArg('--dataset')
   const versionLabel = getArg('--label') || getArg('--version-label') || null
@@ -151,7 +129,8 @@ async function createDatasetVersion() {
 
   const readmeMarkdown = readReadmeMarkdownFromArgs(usage)
   const resolvedDatasetId = await resolveDatasetIdForProject(datasetId, project)
-  const data = await requestDatasetVersionSnapshot(resolvedDatasetId, {
+  const { createDatasetVersionSnapshot } = await import('./dataset-version-workflow.js')
+  const data = await createDatasetVersionSnapshot(resolvedDatasetId, {
     versionLabel,
     readmeMarkdown,
   })
@@ -174,6 +153,36 @@ async function createDatasetVersion() {
   )
 }
 
+async function listDatasetSplitSets() {
+  const versionId = getPositionalArg(3)
+  if (!versionId) throw new Error('Usage: orizu datasets splits list <datasetVersionId> [--json]')
+  const { listDatasetSplits } = await import('./dataset-split-reads.js')
+  const data = await listDatasetSplits(versionId)
+  if (hasJsonFlag()) return printJson({ ...data })
+  printLine(`Dataset version ${sanitizeTerminalText(data.dataset_version_id)}`)
+  for (const set of data.split_sets) {
+    printLine(`${sanitizeTerminalText(set.name)} (${sanitizeTerminalText(set.id)})`)
+    for (const partition of set.partitions) printLine(`  ${sanitizeTerminalText(partition.name)}: ${partition.row_count} rows`)
+  }
+  if (!data.split_sets.length) printLine('No saved split sets.')
+}
+
+async function showDatasetSplitSet() {
+  const setId = getPositionalArg(3)
+  if (!setId) throw new Error('Usage: orizu datasets splits show <splitSetId> [--json]')
+  const { showDatasetSplit } = await import('./dataset-split-reads.js')
+  const data = await showDatasetSplit(setId)
+  if (hasJsonFlag()) return printJson({ ...data })
+  printLine(`${sanitizeTerminalText(data.name)} (${sanitizeTerminalText(data.split_set_id)})`)
+  printLine(`Dataset version: ${sanitizeTerminalText(data.dataset_version_id)}`)
+  printLine(`Strategy: ${sanitizeTerminalText(data.strategy)}; seed: ${data.seed ?? 'none'}`)
+  printLine(`Metadata: ${sanitizeTerminalText(JSON.stringify(data.metadata))}`)
+  for (const partition of data.partitions) {
+    printLine(`${sanitizeTerminalText(partition.name)}: ${partition.row_ids.length} rows`)
+    for (const id of partition.row_ids) printLine(`  ${sanitizeTerminalText(id)}`)
+  }
+}
+
 async function createDatasetSplitSet() {
   const datasetVersionId = getPositionalArg(3) || getArg('--dataset-version')
   const splitFile = getArg('--from-file')
@@ -194,7 +203,7 @@ async function createDatasetSplitSet() {
   }
 
   const partitions = splitSpec && Array.isArray(splitSpec.partitions) ? splitSpec.partitions : undefined
-  const metadata = splitSpec && typeof splitSpec.metadata === 'object' && splitSpec.metadata !== null
+  const metadata = splitSpec && Object.prototype.hasOwnProperty.call(splitSpec, 'metadata')
     ? splitSpec.metadata
     : undefined
 
@@ -351,37 +360,21 @@ async function setDatasetReadme() {
   }
 
   const resolvedDatasetId = await resolveDatasetIdForProject(datasetId, project)
-  const response = await authedFetch(`/api/cli/datasets/${encodeURIComponent(resolvedDatasetId)}/readme`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ markdown: readmeMarkdown }),
-  })
-
-  if (!response.ok) {
-    throw new Error(`Failed to save dataset README: ${await response.text()}`)
-  }
-
-  const data = await parseJsonResponse<{
-    version: {
-      id: string
-      dataset_id: string
-      version_num: number
-      created_at: string
-    }
-  }>(response, 'Dataset README save')
+  const { saveDatasetReadme } = await import('./dataset-readme-workflow.js')
+  const version = await saveDatasetReadme(resolvedDatasetId, readmeMarkdown)
 
   if (hasJsonFlag()) {
     printJson({
-      dataset_id: data.version.dataset_id,
-      readme_version_id: data.version.id,
-      readme_version_num: data.version.version_num,
+      dataset_id: version.dataset_id,
+      readme_version_id: version.id,
+      readme_version_num: version.version_num,
     })
     return
   }
 
   printLine(
-    `Saved README v${data.version.version_num} for dataset ` +
-    `${sanitizeTerminalText(data.version.dataset_id)} (${sanitizeTerminalText(data.version.id)}).`
+    `Saved README v${version.version_num} for dataset ` +
+    `${sanitizeTerminalText(version.dataset_id)} (${sanitizeTerminalText(version.id)}).`
   )
 }
 
@@ -409,6 +402,21 @@ async function downloadDataset() {
     throw new Error('format must be one of: csv, json, jsonl')
   }
 
+  const versionId = getArg('--dataset-version'), setId = getArg('--split-set')
+  const inlineSplit = cliArgs.find(argument => argument.startsWith('--split='))
+  const split = inlineSplit === undefined ? getArg('--split') : inlineSplit.slice('--split='.length)
+  if (['--dataset-version', '--split-set', '--split'].some(flag => hasArg(flag) || cliArgs.some(argument => argument.startsWith(`${flag}=`)))) {
+    if (!versionId || !setId || !split || [versionId, setId].some(value => value.startsWith('--')) || (inlineSplit === undefined && split.startsWith('--'))) throw new Error('Pinned download requires --dataset-version, --split-set and --split together')
+    if (datasetInput) throw new Error('Use --dataset-version with split selectors without a live --dataset or dataset argument')
+    if (format === 'csv') throw new Error('Pinned download format must be json or jsonl')
+    const filename = outPathArg ? expandHomePath(outPathArg) : `${versionId}.${format}`
+    const { downloadPinnedDatasetSplit } = await import('./dataset-split-reads.js')
+    await downloadPinnedDatasetSplit(versionId, setId, split, format, filename)
+    if (hasJsonFlag()) return printJson({ dataset_version_id: versionId, split_set_id: setId, split, format, savedTo: filename })
+    printLine(`Saved split ${sanitizeTerminalText(split)} from dataset version ${sanitizeTerminalText(versionId)} (${format.toUpperCase()}) to ${sanitizeTerminalText(filename)}`)
+    return
+  }
+
   let datasetId: string
   if (datasetInput) {
     datasetId = parseDatasetReference(datasetInput).datasetId
@@ -460,7 +468,8 @@ async function editDatasetRows() {
     datasetId = selected.datasetId
   }
 
-  await runEditDatasetRows({
+  const { editDatasetRows: runEditDatasetRows } = await import('./dataset-row-workflow.js')
+  const exitCode = await runEditDatasetRows({
     datasetId,
     file: expandHomePath(fileArg),
     json: hasJsonFlag(),
@@ -468,6 +477,7 @@ async function editDatasetRows() {
     printLine,
     sanitize: sanitizeTerminalText,
   })
+  if (exitCode !== 0) process.exitCode = exitCode
 }
 
 async function deleteDatasetRows() {
@@ -487,30 +497,16 @@ async function deleteDatasetRows() {
     datasetId = selected.datasetId
   }
 
-  const response = await authedFetch(`/api/cli/datasets/${encodeURIComponent(datasetId)}/rows`, {
-    method: 'DELETE',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      rowIds,
-    }),
+  const { deleteDatasetRows: runDeleteDatasetRows } = await import('./dataset-row-workflow.js')
+  const exitCode = await runDeleteDatasetRows({
+    datasetId,
+    rowIds,
+    json: hasJsonFlag(),
+    printJson,
+    printLine,
+    sanitize: sanitizeTerminalText,
   })
-
-  if (!response.ok) {
-    throw new Error(`Delete rows failed: ${await response.text()}`)
-  }
-
-  const data = await parseJsonResponse<{
-    dataset: { id: string; name: string; rowCount: number }
-    deletedCount: number
-  }>(response, 'Dataset delete rows')
-
-  if (hasJsonFlag()) {
-    printJson({ dataset: data.dataset, deletedCount: data.deletedCount })
-    return
-  }
-  printLine(
-    `Deleted ${data.deletedCount} rows from dataset ${sanitizeTerminalText(data.dataset.name)} (${sanitizeTerminalText(data.dataset.id)}). New row count: ${data.dataset.rowCount}`
-  )
+  if (exitCode !== 0) process.exitCode = exitCode
 }
 
 async function confirmDatasetDeletion(dataset: DatasetSelection) {
@@ -550,23 +546,16 @@ async function deleteDataset() {
 
   await confirmDatasetDeletion(dataset)
 
-  const response = await authedFetch(`/api/cli/datasets/${encodeURIComponent(dataset.datasetId)}`, {
-    method: 'DELETE',
-  })
-
-  if (!response.ok) {
-    throw new Error(`Delete failed: ${await response.text()}`)
-  }
-
-  const data = await parseJsonResponse<{
-    dataset: { id: string }
-  }>(response, 'Dataset delete')
+  const { deleteDataset: requestDelete } = await import('./dataset-delete-workflow.js')
+  // Only a dataset picked from a project's list has a known project; with
+  // --dataset, --project is never checked against the dataset.
+  const deleted = await requestDelete(dataset.datasetId, dataset.project ?? null)
 
   if (hasJsonFlag()) {
-    printJson({ dataset: data.dataset, deleted: true })
+    printJson({ dataset: deleted, deleted: true })
     return
   }
-  printLine(`Deleted dataset ${sanitizeTerminalText(data.dataset.id)}.`)
+  printLine(`Deleted dataset ${sanitizeTerminalText(deleted.id)}.`)
 }
 
 async function lockDataset() {
@@ -582,32 +571,15 @@ async function lockDataset() {
     datasetId = selected.datasetId
   }
 
-  const response = await authedFetch(`/api/cli/datasets/${encodeURIComponent(datasetId)}/lock`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(reason ? { reason } : {}),
-  })
-
-  if (!response.ok) {
-    throw new Error(`Lock failed: ${await response.text()}`)
-  }
-
-  const data = await parseJsonResponse<{
-    dataset: {
-      id: string
-      name: string
-      rowCount: number
-      lockedAt: string
-      lockedBy: string | null
-    }
-  }>(response, 'Dataset lock')
+  const { lockDataset: requestLock } = await import('./dataset-lock-workflow.js')
+  const dataset = await requestLock(datasetId, reason)
 
   if (hasJsonFlag()) {
-    printJson({ dataset: data.dataset })
+    printJson({ dataset })
     return
   }
   printLine(
-    `Locked dataset ${sanitizeTerminalText(data.dataset.name)} (${sanitizeTerminalText(data.dataset.id)}) at ${sanitizeTerminalText(data.dataset.lockedAt)}. Row count: ${data.dataset.rowCount}`
+    `Locked dataset ${sanitizeTerminalText(dataset.name)} (${sanitizeTerminalText(dataset.id)}) at ${sanitizeTerminalText(dataset.lockedAt)}. Row count: ${dataset.rowCount}`
   )
 }
 
@@ -624,31 +596,15 @@ async function cloneDataset() {
     datasetId = selected.datasetId
   }
 
-  const response = await authedFetch(`/api/cli/datasets/${encodeURIComponent(datasetId)}/clone`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(name ? { name } : {}),
-  })
-
-  if (!response.ok) {
-    throw new Error(`Clone failed: ${await response.text()}`)
-  }
-
-  const data = await parseJsonResponse<{
-    dataset: {
-      id: string
-      name: string
-      rowCount: number
-      parentDatasetId: string
-    }
-  }>(response, 'Dataset clone')
+  const { cloneDataset: requestClone } = await import('./dataset-clone-workflow.js')
+  const dataset = await requestClone(datasetId, name ?? null)
 
   if (hasJsonFlag()) {
-    printJson({ dataset: data.dataset })
+    printJson({ dataset })
     return
   }
   printLine(
-    `Cloned dataset ${sanitizeTerminalText(data.dataset.parentDatasetId)} -> ${sanitizeTerminalText(data.dataset.name)} (${sanitizeTerminalText(data.dataset.id)}). Row count: ${data.dataset.rowCount}`
+    `Cloned dataset ${sanitizeTerminalText(dataset.parentDatasetId)} -> ${sanitizeTerminalText(dataset.name)} (${sanitizeTerminalText(dataset.id)}). Row count: ${dataset.rowCount}`
   )
 }
 
@@ -665,18 +621,13 @@ async function downloadAnnotations() {
     taskId = await selectTaskIdInteractively()
   }
 
-  const response = await authedFetch(`/api/cli/tasks/${taskId}/export?format=${format}`)
-  if (!response.ok) {
-    throw new Error(`Download failed: ${await response.text()}`)
-  }
-
   const fallbackName = `${taskId}.${format}`
   const filename = outPathArg
     ? expandHomePath(outPathArg)
     : fallbackName
 
-  const bytes = new Uint8Array(await response.arrayBuffer())
-  writeFileSync(filename, bytes)
+  const { runTaskExportDownload } = await import('./task-export-workflow.js')
+  await runTaskExportDownload(taskId, format, filename)
 
   if (hasJsonFlag()) {
     printJson({ taskId, format, savedTo: filename })
@@ -694,6 +645,8 @@ export {
   setDatasetReadme,
   createDatasetVersion,
   createDatasetSplitSet,
+  listDatasetSplitSets,
+  showDatasetSplitSet,
   editDatasetRows,
   deleteDatasetRows,
   deleteDataset,

package/src/dataset-delete-workflow.ts

@@ -0,0 +1,72 @@
+import { Cause, Effect, Exit, Result, Schema } from 'effect'
+
+import { datasetTransferTimeoutMs } from './dataset-transfer-policy.js'
+import { authedFetch } from './http.js'
+import { parseJsonResponse } from './json-response.js'
+
+// Loaded only through `await import(...)` from dataset-commands, like append.
+
+const MAY_BE_DELETED = 'The dataset may already be deleted: check with `orizu datasets list --status all` before retrying.'
+
+const DeleteReply = Schema.Struct({ dataset: Schema.Struct({ id: Schema.String }) })
+
+// A refusal (4xx) means nothing was deleted. After any other failure once the
+// request was sent, the delete may have committed, and it cannot be undone.
+class DeleteFailure extends Error {
+  constructor(message: string, readonly mayBeDeleted: boolean) { super(message) }
+}
+
+function deleteRequest(datasetId: string, project: string | null, timeoutMs: number) {
+  return Effect.suspend(() => {
+    let sent = false
+    let timedOut = false
+    return Effect.tryPromise({
+      try: async signal => {
+        const request = new AbortController()
+        const abort = () => request.abort()
+        const timer = setTimeout(() => { timedOut = true; request.abort() }, timeoutMs)
+        if (signal.aborted) abort()
+        else signal.addEventListener('abort', abort, { once: true })
+        try {
+          const response = await authedFetch(`/api/cli/datasets/${encodeURIComponent(datasetId)}`, {
+            method: 'DELETE',
+            signal: request.signal,
+          }, () => { sent = true })
+          if (!response.ok) {
+            const message = `Delete failed: ${await response.text()}`
+            // A dependency refusal: archiving keeps the dataset and its references.
+            if (response.status === 409) {
+              const archive = `orizu datasets archive ${datasetId}${project ? ` --project ${project}` : ''}`
+              throw new DeleteFailure(`${message}\nArchive it instead: \`${archive}\``, false)
+            }
+            throw new DeleteFailure(message, response.status < 400 || response.status >= 500)
+          }
+          const data = await parseJsonResponse<unknown>(response, 'Dataset delete')
+          const decoded = Schema.decodeUnknownResult(DeleteReply)(data)
+          if (Result.isFailure(decoded)) {
+            throw new DeleteFailure(`Dataset delete returned an unexpected response (status ${response.status}).`, true)
+          }
+          return decoded.success.dataset
+        } finally {
+          clearTimeout(timer)
+          signal.removeEventListener('abort', abort)
+          request.abort()
+        }
+      },
+      catch: cause => {
+        if (timedOut) return new DeleteFailure('DATASET_TRANSFER_TIMEOUT: Dataset delete exceeded its deadline', true)
+        if (cause instanceof DeleteFailure) return cause
+        return new DeleteFailure(cause instanceof Error ? cause.message : String(cause), sent)
+      },
+    })
+  }).pipe(Effect.mapError(failure => new Error(failure.mayBeDeleted ? `${failure.message}\n${MAY_BE_DELETED}` : failure.message)))
+}
+
+// Runs after the typed confirmation. Nothing to clean up, so signals keep
+// Node's default handling.
+// `project` (team/project), when known, goes into the archive hint.
+export async function deleteDataset(datasetId: string, project: string | null): Promise<{ id: string }> {
+  const exit = await Effect.runPromiseExit(deleteRequest(datasetId, project, datasetTransferTimeoutMs()))
+  if (Exit.isSuccess(exit)) return exit.value
+  throw Cause.squash(exit.cause)
+}

package/src/dataset-lock-workflow.ts

@@ -0,0 +1,74 @@
+import { Cause, Effect, Exit, Result, Schema } from 'effect'
+
+import { datasetTransferTimeoutMs } from './dataset-transfer-policy.js'
+import { authedFetch } from './http.js'
+import { parseJsonResponse } from './json-response.js'
+
+// Loaded only through `await import(...)` from dataset-commands, like append.
+
+const MAY_BE_LOCKED = 'The dataset may already be locked: running `orizu datasets lock` again is safe and shows its current state.'
+
+const LockedDataset = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  rowCount: Schema.Number,
+  lockedAt: Schema.String,
+  lockedBy: Schema.NullOr(Schema.String),
+})
+const LockReply = Schema.Struct({ dataset: LockedDataset })
+export type LockedDataset = typeof LockedDataset.Type
+
+// A refusal (4xx) means nothing was locked. After any other failure once the
+// request was sent, the lock may have committed; locking again is harmless.
+class LockFailure extends Error {
+  constructor(message: string, readonly mayBeLocked: boolean) { super(message) }
+}
+
+function lockRequest(datasetId: string, reason: string | null, timeoutMs: number) {
+  return Effect.suspend(() => {
+    let sent = false
+    let timedOut = false
+    return Effect.tryPromise({
+      try: async signal => {
+        const request = new AbortController()
+        const abort = () => request.abort()
+        const timer = setTimeout(() => { timedOut = true; request.abort() }, timeoutMs)
+        if (signal.aborted) abort()
+        else signal.addEventListener('abort', abort, { once: true })
+        try {
+          const response = await authedFetch(`/api/cli/datasets/${encodeURIComponent(datasetId)}/lock`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(reason ? { reason } : {}),
+            signal: request.signal,
+          }, () => { sent = true })
+          if (!response.ok) {
+            throw new LockFailure(`Lock failed: ${await response.text()}`, response.status < 400 || response.status >= 500)
+          }
+          const data = await parseJsonResponse<unknown>(response, 'Dataset lock')
+          const decoded = Schema.decodeUnknownResult(LockReply)(data)
+          if (Result.isFailure(decoded)) {
+            throw new LockFailure(`Dataset lock returned an unexpected response (status ${response.status}).`, true)
+          }
+          return decoded.success.dataset
+        } finally {
+          clearTimeout(timer)
+          signal.removeEventListener('abort', abort)
+          request.abort()
+        }
+      },
+      catch: cause => {
+        if (timedOut) return new LockFailure('DATASET_TRANSFER_TIMEOUT: Dataset lock exceeded its deadline', true)
+        if (cause instanceof LockFailure) return cause
+        return new LockFailure(cause instanceof Error ? cause.message : String(cause), sent)
+      },
+    })
+  }).pipe(Effect.mapError(failure => new Error(failure.mayBeLocked ? `${failure.message}\n${MAY_BE_LOCKED}` : failure.message)))
+}
+
+// Nothing to clean up, so signals keep Node's default handling.
+export async function lockDataset(datasetId: string, reason: string | null): Promise<LockedDataset> {
+  const exit = await Effect.runPromiseExit(lockRequest(datasetId, reason, datasetTransferTimeoutMs()))
+  if (Exit.isSuccess(exit)) return exit.value
+  throw Cause.squash(exit.cause)
+}