orizu 0.5.41 → 0.5.43

package/src/archive-artifact-workflow.ts

@@ -0,0 +1,101 @@
+import { Cause, Effect, Exit, Result, Schema } from 'effect'
+
+import { datasetTransferTimeoutMs } from './dataset-transfer-policy.js'
+import { isJsonErrorResponsePayload } from './error-response.js'
+import { authedFetch } from './http.js'
+import { sanitizeTerminalText } from './json-response.js'
+
+// Loaded only through `await import(...)` from archive-artifacts-cli.
+
+const MAY_BE_SAVED = 'The change may already be saved: running the same command again is safe and shows its current state.'
+
+const ArchiveReply = Schema.Struct({
+  artifact: Schema.Struct({
+    id: Schema.String,
+    type: Schema.String,
+    status: Schema.Literals(['active', 'archived']),
+    archivedAt: Schema.NullOr(Schema.String),
+    assigneeId: Schema.optionalKey(Schema.String),
+  }),
+})
+export type ArchiveReply = typeof ArchiveReply.Type
+
+export interface ArchiveRequest {
+  path: string
+  body: { archived: boolean; assigneeId?: string }
+  // For example "archive dataset": the start of every failure message.
+  label: string
+  fetcher?: (path: string, init?: RequestInit) => Promise<Response>
+}
+
+// A refusal (4xx) means nothing changed. After any other failure once the
+// request was sent, the change may have committed; repeating it is harmless.
+class ArchiveFailure extends Error {
+  constructor(message: string, readonly mayBeSaved: boolean) { super(message) }
+}
+
+async function reason(response: Response): Promise<string> {
+  const text = await response.text()
+  let payload: unknown = null
+  try { payload = JSON.parse(text) } catch { /* not JSON */ }
+  if (isJsonErrorResponsePayload(response, payload) && payload.error.length > 0) {
+    return sanitizeTerminalText(payload.error).slice(0, 180)
+  }
+  // Never print a page body: a gateway's HTML says nothing useful.
+  return `the server returned a page that isn't JSON (status ${response.status})`
+}
+
+function archiveRequest(request: ArchiveRequest, timeoutMs: number) {
+  return Effect.suspend(() => {
+    let sent = false
+    let timedOut = false
+    return Effect.tryPromise({
+      try: async signal => {
+        const controller = new AbortController()
+        const abort = () => controller.abort()
+        const timer = setTimeout(() => { timedOut = true; controller.abort() }, timeoutMs)
+        if (signal.aborted) abort()
+        else signal.addEventListener('abort', abort, { once: true })
+        try {
+          const init: RequestInit = {
+            method: 'PATCH',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(request.body),
+            signal: controller.signal,
+          }
+          const response = request.fetcher
+            ? (sent = true, await request.fetcher(request.path, init))
+            : await authedFetch(request.path, init, () => { sent = true })
+          if (!response.ok) {
+            throw new ArchiveFailure(`Failed to ${request.label}: ${await reason(response)}`, response.status < 400 || response.status >= 500)
+          }
+          let data: unknown = null
+          try { data = JSON.parse(await response.text()) } catch { /* decoded below */ }
+          const decoded = Schema.decodeUnknownResult(ArchiveReply)(data)
+          if (Result.isFailure(decoded)) {
+            throw new ArchiveFailure(`Failed to ${request.label}: the server's answer could not be read (status ${response.status})`, true)
+          }
+          return decoded.success
+        } finally {
+          clearTimeout(timer)
+          signal.removeEventListener('abort', abort)
+          controller.abort()
+        }
+      },
+      catch: cause => {
+        if (timedOut) return new ArchiveFailure(`Failed to ${request.label}: the request exceeded its deadline`, true)
+        if (cause instanceof ArchiveFailure) return cause
+        const message = cause instanceof Error ? cause.message : String(cause)
+        // Before sending (for example, not signed in) the message stands alone.
+        return new ArchiveFailure(sent ? `Failed to ${request.label}: ${message}` : message, sent)
+      },
+    })
+  }).pipe(Effect.mapError(failure => new Error(failure.mayBeSaved ? `${failure.message}\n${MAY_BE_SAVED}` : failure.message)))
+}
+
+// Nothing to clean up, so signals keep Node's default handling.
+export async function archiveArtifact(request: ArchiveRequest): Promise<ArchiveReply> {
+  const exit = await Effect.runPromiseExit(archiveRequest(request, datasetTransferTimeoutMs()))
+  if (Exit.isSuccess(exit)) return exit.value
+  throw Cause.squash(exit.cause)
+}

package/src/archive-artifacts-cli.ts

@@ -27,14 +27,6 @@ export interface ArchiveArtifactsIo {
   fetcher?: (path: string, init?: RequestInit) => Promise<Response>
 }
 
-interface ArchiveArtifactResult {
-  id: string
-  type: ArchiveArtifactType
-  status: 'active' | 'archived'
-  archivedAt: string | null
-  assigneeId?: string
-}
-
 interface AssignmentSummary {
   taskId: string
   taskTitle: string
@@ -262,27 +254,14 @@ export async function archiveArtifactCommand(
     archived: action === 'archive',
     ...(assigneeId ? { assigneeId } : {}),
   }
-  const fetcher = io.fetcher || authedFetch
-  const response = await fetcher(
-    `/api/cli/archive-artifacts/${artifactType}/${encodeURIComponent(artifactId)}` +
+  const { archiveArtifact } = await import('./archive-artifact-workflow.js')
+  const data = await archiveArtifact({
+    path: `/api/cli/archive-artifacts/${artifactType}/${encodeURIComponent(artifactId)}` +
       `?${params.toString()}`,
-    {
-      method: 'PATCH',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify(body),
-    }
-  )
-  if (!response.ok) {
-    throw new Error(
-      `Failed to ${action} ${artifactType}: ` +
-      await extractErrorMessage(response)
-    )
-  }
-
-  const data = await parseJsonPayload<{ artifact: ArchiveArtifactResult }>(
-    response,
-    `${action === 'archive' ? 'Archive' : 'Restore'} ${artifactType}`
-  )
+    body,
+    label: `${action} ${artifactType}`,
+    fetcher: io.fetcher,
+  })
   if (io.json) {
     io.print(JSON.stringify(data))
     return

package/src/artifact-archive.ts

@@ -1,3 +1,5 @@
+// Reads only the artifact folder it is given.
+// @tia-reads: none
 import { createHash } from 'crypto'
 import { readdirSync, readFileSync, statSync } from 'fs'
 import { join } from 'path'

package/src/credentials.ts

@@ -1,3 +1,5 @@
+// Reads only the user's credential, lock and token files.
+// @tia-reads: none
 import {
   chmodSync,
   closeSync,

package/src/dataset-commands.ts

@@ -20,8 +20,7 @@ import {
   selectDatasetInteractively,
   selectTaskIdInteractively,
 } from './account-directory.js'
-import { sanitizeTerminalText, parseJsonResponse } from './json-response.js'
-import { authedFetch } from './http.js'
+import { sanitizeTerminalText } from './json-response.js'
 import { printJson, printLine } from './cli-console-output.js'
 import { readJsonFile } from './app-commands.js'
 import { printDatasetSummaries } from './archive-artifacts-cli.js'
@@ -78,15 +77,16 @@ function parseRatioFlag(name: string, fallback: number): number {
   return parsed
 }
 
-function parsePositiveIntegerFlag(name: string, fallback: number): number {
+// The app accepts 0 and stores seeds as 32-bit integers.
+function parseSeedFlag(name: string, fallback: number): number {
   const value = getArg(name)
   if (!value) {
     return fallback
   }
 
   const parsed = Number(value)
-  if (!Number.isInteger(parsed) || parsed <= 0) {
-    throw new Error(`${name} must be a positive integer`)
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 2147483647) {
+    throw new Error(`${name} must be a whole number from 0 to 2147483647`)
   }
 
   return parsed
@@ -189,12 +189,15 @@ async function createDatasetSplitSet() {
   const splitSpec = splitFile ? readJsonFile(splitFile) : null
   const name = getArg('--name') || (typeof splitSpec?.name === 'string' ? splitSpec.name : 'default')
   const strategy = getArg('--strategy') || (typeof splitSpec?.strategy === 'string' ? splitSpec.strategy : 'random')
-  const seed = splitSpec && (splitSpec.seed === null || typeof splitSpec.seed === 'number')
+  // A file's seed goes to the app as written, so one that isn't a whole number
+  // is refused there instead of quietly replaced.
+  const seed = splitSpec && Object.prototype.hasOwnProperty.call(splitSpec, 'seed')
     ? splitSpec.seed
-    : parsePositiveIntegerFlag('--seed', 1)
+    : parseSeedFlag('--seed', 1)
   const train = parseRatioFlag('--train', 0.7)
   const validation = parseRatioFlag('--validation', 0.2)
-  const test = parseRatioFlag('--test', 0.1)
+  // Without --test, test takes whatever train and validation leave.
+  const test = getArg('--test') ? parseRatioFlag('--test', 0) : undefined
 
   if (!datasetVersionId) {
     throw new Error(
@@ -202,37 +205,22 @@ async function createDatasetSplitSet() {
     )
   }
 
-  const partitions = splitSpec && Array.isArray(splitSpec.partitions) ? splitSpec.partitions : undefined
+  const { createSplitSet, splitRatioProblem } = await import('./dataset-split-create-workflow.js')
+  const ratioProblem = splitRatioProblem(train, validation, test)
+  if (ratioProblem) throw new Error(ratioProblem)
+
+  const partitions = splitSpec && Object.prototype.hasOwnProperty.call(splitSpec, 'partitions') ? splitSpec.partitions : undefined
   const metadata = splitSpec && Object.prototype.hasOwnProperty.call(splitSpec, 'metadata')
     ? splitSpec.metadata
     : undefined
 
-  const response = await authedFetch(`/api/cli/dataset-versions/${encodeURIComponent(datasetVersionId)}/split-sets`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      name,
-      strategy,
-      seed,
-      train,
-      validation,
-      test,
-      partitions,
-      metadata,
-    }),
-  })
-
-  if (!response.ok) {
-    throw new Error(`Failed to create dataset split set: ${await response.text()}`)
-  }
-
-  const data = await parseJsonResponse<{ splitSet: { id: string } }>(response, 'Dataset split set create')
+  const splitSetId = await createSplitSet({ versionId: datasetVersionId, name, strategy, seed, train, validation, test, partitions, metadata })
   if (hasJsonFlag()) {
-    printJson({ split_set_id: data.splitSet.id })
+    printJson({ split_set_id: splitSetId })
     return
   }
 
-  printLine(`Created split set ${sanitizeTerminalText(data.splitSet.id)}`)
+  printLine(`Created split set ${sanitizeTerminalText(splitSetId)}`)
 }
 
 async function listDatasets() {

package/src/dataset-split-create-workflow.ts

@@ -0,0 +1,128 @@
+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 clone.
+
+const SERVER_MAY_BE_CREATED = 'Dataset split set may already be created'
+// Ratios like 0.7 + 0.2 + 0.1 don't add up to exactly 1 in floating point.
+const RATIO_GAP = 1e-9
+
+const CreateReply = Schema.Struct({ splitSet: Schema.Struct({ id: Schema.String }) })
+const ErrorReply = Schema.Struct({ error: Schema.String })
+
+export interface SplitSetRequest {
+  versionId: string
+  name: string
+  strategy: string
+  seed: unknown
+  train: number
+  validation: number
+  /** Absent means "whatever train and validation leave". */
+  test: number | undefined
+  partitions: unknown
+  metadata: unknown
+}
+
+const shown = (value: number) => Math.round(value * 1e12) / 1e12
+
+/** The same rule the app enforces, checked before anything is sent. */
+export function splitRatioProblem(train: number, validation: number, test: number | undefined): string | null {
+  if (train + validation > 1 + RATIO_GAP) return `--train plus --validation must not be more than 1 (they add up to ${shown(train + validation)})`
+  if (test !== undefined && Math.abs(train + validation + test - 1) > RATIO_GAP) {
+    return `--train, --validation and --test must add up to 1 (they add up to ${shown(train + validation + test)})`
+  }
+  return null
+}
+
+// A refusal means nothing was saved. After any other failure once the request
+// was sent, the set may exist. The version allows one set per name, so running
+// the same command again can't make a second copy; it is still never retried
+// automatically, and the user is told how to check.
+class SplitSetFailure extends Error {
+  constructor(message: string, readonly mayBeCreated: boolean) { super(message) }
+}
+
+function mayBeCreatedGuidance(request: SplitSetRequest): string {
+  return `The split set ${JSON.stringify(request.name)} may already have been created. Run \`orizu datasets splits list ${request.versionId}\` to check. Running the same command again is safe: a set with that name is refused, not duplicated.`
+}
+
+// authedFetch raises this code only when it sent nothing, or when the server
+// answered 401 and the changed credentials stopped a replay. Nothing was saved.
+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 createRequest(request: SplitSetRequest, timeoutMs: number) {
+  return Effect.suspend(() => {
+    let sent = false
+    let timedOut = false
+    return Effect.tryPromise({
+      try: async signal => {
+        const abortController = new AbortController()
+        const abort = () => abortController.abort()
+        const timer = setTimeout(() => { timedOut = true; abortController.abort() }, timeoutMs)
+        if (signal.aborted) abort()
+        else signal.addEventListener('abort', abort, { once: true })
+        try {
+          const response = await authedFetch(`/api/cli/dataset-versions/${encodeURIComponent(request.versionId)}/split-sets`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              name: request.name,
+              strategy: request.strategy,
+              seed: request.seed,
+              train: request.train,
+              validation: request.validation,
+              test: request.test,
+              partitions: request.partitions,
+              metadata: request.metadata,
+            }),
+            signal: abortController.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 set.
+            const mayBeCreated = response.status < 400 || error === SERVER_MAY_BE_CREATED || (response.status >= 500 && error === null)
+            throw new SplitSetFailure(`Failed to create dataset split set: ${text}`, mayBeCreated)
+          }
+          const data = await parseJsonResponse<unknown>(response, 'Dataset split set create')
+          const decoded = Schema.decodeUnknownResult(CreateReply)(data)
+          if (Result.isFailure(decoded)) {
+            throw new SplitSetFailure(`Dataset split set create returned an unexpected response (status ${response.status}).`, true)
+          }
+          return decoded.success.splitSet.id
+        } finally {
+          clearTimeout(timer)
+          signal.removeEventListener('abort', abort)
+          abortController.abort()
+        }
+      },
+      catch: cause => {
+        if (timedOut) return new SplitSetFailure('DATASET_TRANSFER_TIMEOUT: Dataset split set create exceeded its deadline', sent)
+        if (cause instanceof SplitSetFailure) return cause
+        return new SplitSetFailure(cause instanceof Error ? cause.message : String(cause), sent && !isAuthContextChange(cause))
+      },
+    })
+  }).pipe(Effect.mapError(failure => new Error(failure.mayBeCreated ? `${failure.message}\n${mayBeCreatedGuidance(request)}` : failure.message)))
+}
+
+// Nothing to clean up, so signals keep Node's default handling.
+export async function createSplitSet(request: SplitSetRequest): Promise<string> {
+  const exit = await Effect.runPromiseExit(createRequest(request, datasetTransferTimeoutMs()))
+  if (Exit.isSuccess(exit)) return exit.value
+  throw Cause.squash(exit.cause)
+}

package/src/git-credential.ts

@@ -377,7 +377,7 @@ async function mintArtifactsCredential(
     `/api/cli/workspaces/${encodeURIComponent(workspaceId)}/repo-token`,
     {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
+      headers: { 'Content-Type': 'application/json', 'X-Orizu-Session-Seed-Protocol': '1' },
       body: JSON.stringify({ purpose, ...(purpose === 'team_read' ? { sessionId: process.env.ORIZU_SESSION_ID?.trim() } : {}) }),
     }
   )

package/src/help.ts

@@ -966,9 +966,17 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
   },
   {
     path: ['datasets', 'splits', 'create'],
-    usage: 'orizu datasets splits create <datasetVersionId> [--from-file <split.json>] [--json]',
-    summary: 'Create a split set for the explicit target dataset version. --from-file accepts splits show JSON; canonical row IDs must exist in the target.',
+    usage: 'orizu datasets splits create <datasetVersionId> [--from-file <split.json>] [--name <name>] [--seed <n>] [--train <ratio>] [--validation <ratio>] [--test <ratio>] [--json]',
+    summary: 'Create a split set for the explicit target dataset version. --from-file accepts splits show JSON; canonical row IDs must exist in the target. Each version allows one set per name.',
     group: 'Datasets',
+    options: [
+      { name: '--from-file <split.json>', help: 'Saved partitions to import, for example from splits show --json.' },
+      { name: '--name <name>', help: 'Set name; defaults to the file name field, then "default".' },
+      { name: '--seed <n>', help: 'Whole number from 0 to 2147483647 for a random split (default 1). The same seed gives the same rows.' },
+      { name: '--train <ratio>', help: 'Share of rows for train, from 0 to 1 (default 0.7).' },
+      { name: '--validation <ratio>', help: 'Share of rows for validation (default 0.2). Train plus validation must not be more than 1.' },
+      { name: '--test <ratio>', help: 'Share of rows for test. Defaults to what train and validation leave; if given, the three must add up to 1.' },
+    ],
   },
   {
     path: ['datasets', 'download'],