@sixb/cli-core 0.1.9 → 0.2.0

package/src/commands/memory.ts

@@ -0,0 +1,358 @@
+import { lstat, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { isHelp } from "../arguments"
+import {
+  AGENT_MEMORY_ENTRY,
+  AGENT_MEMORY_MANIFEST,
+  AGENT_MEMORY_STARTER,
+  type AgentMemoryManifest,
+  type AgentMemoryManifestRepo,
+  type AgentMemoryRepo,
+  agentMemoryFileHash,
+} from "../memory"
+import { CliError, EXIT_API, fail, writeJson, writeText } from "../output"
+import { createInstanceApiClient, type SandboxInstanceCliMode } from "../run"
+import { asRecord, isFileError } from "./shared"
+
+const HELP = `Usage:
+  sixb memory save <repo> -m <message>   Save local edits as one revision
+  sixb memory pull [repo]                Bring the local copy up to the latest revision
+
+<repo> is user or project. Files live under $SIXB_MEMORY_DIR/<repo>/.
+
+A save is rejected for files another conversation changed since they were loaded. Their
+current contents are written next to yours as <file>.theirs: merge each into its file, delete
+it, then save again. Changes others made to other files are brought in by save and pull.`
+
+interface RemoteRepo {
+  readonly revision: number
+  readonly files: ReadonlyMap<string, string>
+}
+
+interface MemoryConflict {
+  readonly path: string
+  /** Where their version was written, or `null` when another save deleted the file. */
+  readonly theirs: string | null
+}
+
+const THEIRS = ".theirs"
+const CONFLICT_HINT = "Merge each .theirs file into its file, delete it, then save again."
+
+export async function memory(args: readonly string[], mode: SandboxInstanceCliMode): Promise<void> {
+  const [sub, ...rest] = args
+  if (!sub || isHelp(sub) || rest.some(isHelp)) return writeText(HELP)
+  const local = localMemory()
+  if (sub === "save") return save(local, rest, mode)
+  if (sub === "pull") return pull(local, rest, mode)
+  fail(`Unknown memory command '${sub}'. Run 'sixb memory --help'.`)
+}
+
+async function save(
+  local: LocalMemory,
+  args: readonly string[],
+  mode: SandboxInstanceCliMode
+): Promise<void> {
+  const { repo, message } = parseSaveArgs(args)
+  const manifest = await local.readManifest()
+  const loaded = manifest.repos[repo]
+  if (!loaded)
+    fail(
+      `Memory repo '${repo}' is not installed.`,
+      "invalid_arguments",
+      `Run 'sixb memory pull ${repo}'.`
+    )
+  const files = await local.readRepo(repo)
+  const unresolved = [...files.keys()].filter((path) => path.endsWith(THEIRS))
+  if (unresolved.length > 0) {
+    fail(`Resolve ${unresolved.join(", ")} first.`, "unresolved_conflicts", CONFLICT_HINT)
+  }
+  const changes = [...new Set([...files.keys(), ...Object.keys(loaded.files)])]
+    .sort()
+    .flatMap((path) => {
+      const contents = files.get(path)
+      const changed =
+        (contents === undefined ? undefined : agentMemoryFileHash(contents)) !== loaded.files[path]
+      return changed ? [{ path, contents: contents ?? null }] : []
+    })
+  if (changes.length === 0) {
+    return writeJson({
+      repo,
+      saved: false,
+      changed: [],
+      hint: "No file changed since it was loaded.",
+    })
+  }
+
+  const api = createInstanceApiClient(mode)
+  let saved: Record<string, unknown>
+  try {
+    saved = asRecord(
+      await api.post(`/api/agent-memory/${repo}/revisions`, {
+        baseRevision: loaded.revision,
+        message,
+        changes,
+      })
+    )
+  } catch (error) {
+    if (!(error instanceof CliError) || error.body.status !== 409) throw error
+    const { revision, conflicts } = await update(local, repo, manifest, await fetchRepo(api, repo))
+    process.exitCode = 1
+    return writeJson({ repo, saved: false, revision, conflicts, hint: CONFLICT_HINT })
+  }
+
+  // The saved files are now what the repo holds, so updating does not report them as conflicts.
+  const savedFiles = { ...loaded.files }
+  for (const change of changes) {
+    if (change.contents === null) delete savedFiles[change.path]
+    else savedFiles[change.path] = agentMemoryFileHash(change.contents)
+  }
+  const after: AgentMemoryManifest = {
+    repos: { ...manifest.repos, [repo]: { ...loaded, files: savedFiles } },
+  }
+  const { revision, conflicts } = await update(local, repo, after, await fetchRepo(api, repo))
+  const warnings = Array.isArray(saved.warnings) ? saved.warnings : []
+  writeJson({
+    repo,
+    saved: true,
+    revision,
+    changed: changes.map((change) => change.path),
+    ...(warnings.length > 0 ? { warnings } : {}),
+    ...(conflicts.length > 0 ? { conflicts, hint: CONFLICT_HINT } : {}),
+  })
+}
+
+async function pull(
+  local: LocalMemory,
+  args: readonly string[],
+  mode: SandboxInstanceCliMode
+): Promise<void> {
+  if (args.length > 1) fail("Invalid arguments for 'memory pull'.")
+  const manifest = await local.readManifest()
+  const repos = args[0] === undefined ? installedRepos(manifest) : [parseRepo(args[0])]
+  if (repos.length === 0) {
+    fail("No memory repo is installed.", "invalid_arguments", "Run 'sixb memory pull user'.")
+  }
+
+  const api = createInstanceApiClient(mode)
+  let current = manifest
+  for (const repo of repos) {
+    const result = await update(local, repo, current, await fetchRepo(api, repo))
+    current = result.manifest
+    writeJson({
+      repo,
+      revision: result.revision,
+      updated: result.updated,
+      conflicts: result.conflicts,
+      ...(result.conflicts.length > 0 ? { hint: CONFLICT_HINT } : {}),
+    })
+  }
+}
+
+/**
+ * Bring the local copy of `repo` to `remote`, three ways against the manifest: a file only the
+ * repo changed is updated, a file only this copy changed is kept, and a file both changed gets
+ * the repo's version next to it as `.theirs`. The manifest then records `remote`, so the next save
+ * sends what this copy holds against the latest revision.
+ */
+async function update(
+  local: LocalMemory,
+  repo: AgentMemoryRepo,
+  manifest: AgentMemoryManifest,
+  remote: RemoteRepo
+): Promise<{
+  readonly manifest: AgentMemoryManifest
+  readonly revision: number
+  readonly updated: readonly string[]
+  readonly conflicts: readonly MemoryConflict[]
+}> {
+  const base = manifest.repos[repo]?.files ?? {}
+  const files = await local.readRepo(repo)
+  const updated: string[] = []
+  const conflicts: MemoryConflict[] = []
+
+  for (const path of [
+    ...new Set([...files.keys(), ...remote.files.keys(), ...Object.keys(base)]),
+  ].sort()) {
+    if (path.endsWith(THEIRS)) continue
+    const mine = files.get(path)
+    const theirs = remote.files.get(path)
+    const mineHash = mine === undefined ? undefined : agentMemoryFileHash(mine)
+    const theirsHash = theirs === undefined ? undefined : agentMemoryFileHash(theirs)
+    if (theirsHash === base[path] || theirsHash === mineHash) continue
+    if (mineHash === base[path]) {
+      await local.write(repo, path, theirs)
+      updated.push(path)
+    } else if (theirs === undefined) {
+      conflicts.push({ path, theirs: null })
+    } else {
+      await local.write(repo, `${path}${THEIRS}`, theirs)
+      conflicts.push({ path, theirs: `${path}${THEIRS}` })
+    }
+  }
+  if (
+    !remote.files.has(AGENT_MEMORY_ENTRY) &&
+    !(await local.readRepo(repo)).has(AGENT_MEMORY_ENTRY)
+  ) {
+    await local.write(repo, AGENT_MEMORY_ENTRY, AGENT_MEMORY_STARTER)
+  }
+
+  const next: AgentMemoryManifest = {
+    repos: {
+      ...manifest.repos,
+      [repo]: {
+        revision: remote.revision,
+        files: Object.fromEntries(
+          [...remote.files].map(([path, contents]) => [path, agentMemoryFileHash(contents)])
+        ),
+      },
+    },
+  }
+  await local.writeManifest(next)
+  return { manifest: next, revision: remote.revision, updated, conflicts }
+}
+
+async function fetchRepo(
+  api: ReturnType<typeof createInstanceApiClient>,
+  repo: AgentMemoryRepo
+): Promise<RemoteRepo> {
+  const body = asRecord(await api.get(`/api/agent-memory/${repo}`))
+  const files = Array.isArray(body.files) ? body.files.map(asRecord) : null
+  if (
+    typeof body.revision !== "number" ||
+    !files?.every((file) => typeof file.path === "string" && typeof file.contents === "string")
+  ) {
+    throw new CliError(
+      { code: "invalid_api_response", message: "The Sixb API returned an invalid memory repo." },
+      EXIT_API
+    )
+  }
+  return {
+    revision: body.revision,
+    files: new Map(files.map((file) => [String(file.path), String(file.contents)])),
+  }
+}
+
+interface LocalMemory {
+  readManifest(): Promise<AgentMemoryManifest>
+  writeManifest(manifest: AgentMemoryManifest): Promise<void>
+  /** Every file of the local copy, by path from the repo root. */
+  readRepo(repo: AgentMemoryRepo): Promise<Map<string, string>>
+  /** `undefined` deletes the file. */
+  write(repo: AgentMemoryRepo, path: string, contents: string | undefined): Promise<void>
+}
+
+function localMemory(): LocalMemory {
+  const root = process.env.SIXB_MEMORY_DIR
+  const contextDir = process.env.SIXB_CONTEXT_DIR
+  if (!root || !contextDir) {
+    fail("Agent memory is not available in this run.", "runtime_unavailable")
+  }
+  const manifestPath = join(contextDir, ...AGENT_MEMORY_MANIFEST.split("/"))
+  const fileOf = (repo: AgentMemoryRepo, path: string) => join(root, repo, ...path.split("/"))
+
+  return {
+    async readManifest() {
+      let text: string
+      try {
+        text = await readFile(manifestPath, "utf8")
+      } catch (error) {
+        if (isFileError(error, "ENOENT")) return { repos: {} }
+        throw error
+      }
+      try {
+        return parseManifest(JSON.parse(text))
+      } catch {
+        fail(`Memory manifest '${manifestPath}' is not valid.`, "invalid_json")
+      }
+    },
+
+    async writeManifest(manifest) {
+      await mkdir(dirname(manifestPath), { recursive: true })
+      await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+    },
+
+    async readRepo(repo) {
+      const files = new Map<string, string>()
+      const walk = async (directory: string, prefix: string): Promise<void> => {
+        let entries: string[]
+        try {
+          entries = await readdir(directory)
+        } catch (error) {
+          if (isFileError(error, "ENOENT")) return
+          throw error
+        }
+        for (const name of entries) {
+          const path = prefix ? `${prefix}/${name}` : name
+          const stats = await lstat(join(directory, name))
+          if (stats.isDirectory()) await walk(join(directory, name), path)
+          else if (stats.isFile()) files.set(path, await readFile(join(directory, name), "utf8"))
+          else fail(`Memory file '${repo}/${path}' is not a regular file.`)
+        }
+      }
+      await walk(join(root, repo), "")
+      return files
+    },
+
+    async write(repo, path, contents) {
+      const file = fileOf(repo, path)
+      if (contents === undefined) {
+        await rm(file, { force: true })
+        return
+      }
+      await mkdir(dirname(file), { recursive: true })
+      await writeFile(file, contents)
+    },
+  }
+}
+
+function parseSaveArgs(args: readonly string[]): { repo: AgentMemoryRepo; message: string } {
+  const positionals: string[] = []
+  let message: string | undefined
+  for (let index = 0; index < args.length; index++) {
+    const argument = args[index] ?? ""
+    if (argument === "-m" || argument === "--message") {
+      if (message !== undefined) fail(`${argument} may only be provided once.`)
+      message = args[++index]
+      if (!message) fail(`${argument} requires a value.`)
+    } else if (argument.startsWith("-")) {
+      fail(`Unknown memory save option '${argument}'.`)
+    } else {
+      positionals.push(argument)
+    }
+  }
+  if (positionals.length !== 1) fail("Invalid arguments for 'memory save'.")
+  if (message === undefined || message.trim().length === 0) {
+    fail("memory save requires -m <what you learned>.")
+  }
+  return { repo: parseRepo(positionals[0] ?? ""), message }
+}
+
+function parseRepo(value: string): AgentMemoryRepo {
+  if (value === "user" || value === "project") return value
+  fail(`Unknown memory repo '${value}'. Use 'user' or 'project'.`)
+}
+
+function installedRepos(manifest: AgentMemoryManifest): AgentMemoryRepo[] {
+  return (["user", "project"] as const).filter((repo) => manifest.repos[repo] !== undefined)
+}
+
+function parseManifest(value: unknown): AgentMemoryManifest {
+  const repos = asRecord(asRecord(value).repos)
+  const parsed: Partial<Record<AgentMemoryRepo, AgentMemoryManifestRepo>> = {}
+  for (const repo of ["user", "project"] as const) {
+    if (repos[repo] === undefined) continue
+    const entry = asRecord(repos[repo])
+    const files = asRecord(entry.files)
+    if (
+      typeof entry.revision !== "number" ||
+      !Object.values(files).every((digest) => typeof digest === "string")
+    ) {
+      throw new Error("invalid memory manifest")
+    }
+    parsed[repo] = {
+      revision: entry.revision,
+      files: files as Record<string, string>,
+    }
+  }
+  return { repos: parsed }
+}

package/src/commands/metadata.ts

@@ -5,17 +5,17 @@ import {
   DEFAULT_TELEMETRY_ORDER,
 } from "../policies"
 
-const SANDBOX_MAIN_HELP = `Sixb agent CLI
+const SANDBOX_MAIN_HELP = `Sixb CLI
 
 Usage:
   sixb <command> [options]
 
-The CLI uses the run-scoped SIXB_API_BASE_URL. Do not configure authentication or another origin.
+The CLI uses the run's SIXB_API_BASE_URL, which adds its credentials. Do not configure authentication or another origin.
 API commands emit JSON. Help, version, and examples emit text. Downloads write to --output and
 emit a JSON receipt.
 
 Discovery:
-  sixb doctor                         Check the sandbox and API gateway
+  sixb status                         Check the sandbox and its API access
   sixb context                        Print the current run context
   sixb project show                   Show project metadata
   sixb ontology list                  Compact visible type and relationship catalog
@@ -50,6 +50,13 @@ Actions and workflows:
   sixb workflows list|get|start ...
   sixb workflow-runs list|get ...
 
+Data:
+  sixb datasets list|get|versions|rows ...
+  sixb syncs list|get ...             Syncs you may run, each with its latest run
+  sixb sync-runs list ...
+  sixb pipelines list|get ...         Pipelines you may run, each with its latest run
+  sixb pipeline-runs list|get ...
+
 Files:
   sixb files upload|download ...
 
@@ -63,28 +70,9 @@ A user parameter or property is {"type":"user","id":"<user-id>"}. Find the id wi
 Run \`sixb <group> --help\` or \`sixb <group> <command> --help\` for exact arguments.
 For query IR, run \`sixb objects query --help\` and \`sixb objects query --example list\`.`
 
-const LOCAL_MAIN_HELP = SANDBOX_MAIN_HELP.replace("Sixb agent CLI", "Sixb instance CLI")
-  .replace(
-    "The CLI uses the run-scoped SIXB_API_BASE_URL. Do not configure authentication or another origin.",
-    "The CLI uses the selected local profile and its API credentials."
-  )
-  .replace(
-    "  sixb doctor                         Check the sandbox and API gateway\n  sixb context                        Print the current run context\n",
-    ""
-  )
-  .replace(
-    "\nWhen you do not know a type's properties or links, read its file under $SIXB_ONTOLOGY_DIR. Use\n`sixb ontology get` for a type that has no file there.\n",
-    ""
-  )
-
-  // The agent reaches models through its run's gateway once the model routes allow it.
-  .replace(
-    "Files:\n  sixb files upload|download ...\n",
-    "Files:\n  sixb files upload|download ...\n\nModels:\n  sixb models list [--kind <kind>]    Configured models of every kind, with prices\n  sixb models get <model>             One model's options and rate card\n  sixb models text|image|speech|transcribe ...   Call a model; see sixb models --help\n"
-  )
-
-export function renderInstanceHelp(mode: "local" | "sandbox"): string {
-  return mode === "sandbox" ? SANDBOX_MAIN_HELP : LOCAL_MAIN_HELP
+/** The sandbox CLI's help, which the agent's prompt includes. People's comes from @sixb/cli. */
+export function renderInstanceHelp(): string {
+  return SANDBOX_MAIN_HELP
 }
 
 const SEARCH_DETAILS = `Without --type, search matches primary-id prefixes and full-text fields across visible types.
@@ -214,8 +202,15 @@ Vector profile names are the keys of the type's search.vectors. Vector input is
 optionally under filters; k bounds the ranked matches and results carry a score.`
 
 export const GROUP_HELP = {
-  doctor: "Usage: sixb doctor",
+  status: "Usage: sixb status",
   context: "Usage: sixb context",
+  history: `Usage:
+  sixb history [--offset <n>] [--limit <1-${CLI_LIMITS.history.maximum}>]
+  sixb history <seq>
+
+Prints this conversation's messages as text, oldest first, including those summarized when it
+was compacted: what was said, the files sent, and each tool call with its result. A page holds
+${CLI_LIMITS.history.default} messages by default and cuts long text; \`sixb history <seq>\` prints one message whole.`,
   project: "Usage: sixb project show",
   ontology: `Usage:
   sixb ontology list [--full]
@@ -256,7 +251,8 @@ List options:
   files: `Usage:
   sixb files upload <local-path> [--logical-path <path>]
   sixb files download object <type> <id> --path <json-pointer> --output <local-path>
-  sixb files download action-run|workflow-run <run-id> --path <json-pointer> --output <local-path>`,
+  sixb files download action-run|workflow-run <run-id> --path <json-pointer> --output <local-path>
+  sixb files download url <content-url> --output <local-path>`,
   workflows: `Usage:
   sixb workflows list
   sixb workflows get <workflow-id>
@@ -267,14 +263,15 @@ for the user's approval prints \`"status": "awaiting_approval"\` and exits with
   users: `Usage:
   sixb users list [options]
   sixb users search <text> [options]
-  sixb users get <user-id>
+  sixb users get <user-id|email>
 
 Options:
   --status active|suspended|all       Defaults to active
   --limit <1-${CLI_LIMITS.users.maximum}>                     Defaults to ${CLI_LIMITS.users.default}
   --offset <n>                        Non-negative; defaults to 0
 
-\`users search\` matches part of a display name or email, ignoring case. Each member is
+\`users search\` matches part of a display name or email, ignoring case; \`users get\` takes an
+exact email, ignoring case, and finds suspended members too. Each member is
 {"id","email","displayName","avatarUrl","status"}; a user parameter takes
 {"type":"user","id":"<id>"}. Reading members requires can.view(project.users).`,
   models: `Usage:
@@ -313,6 +310,56 @@ List options:
   --limit <1-${CLI_LIMITS.list.maximum}>              Defaults to ${CLI_LIMITS.list.default}
   --offset <n>                  Non-negative; defaults to 0
   --order <asc|desc>            Started-time order; defaults to ${DEFAULT_LIST_ORDER}`,
+  datasets: `Usage:
+  sixb datasets list
+  sixb datasets get <dataset-id>
+  sixb datasets versions <dataset-id> [--limit <1-${CLI_LIMITS.datasetVersions.maximum}>]
+  sixb datasets rows <dataset-id> [options]
+
+Rows options:
+  --version <version-id>        Defaults to the latest version
+  --columns <a,b,...>           Defaults to every column
+  --limit <1-${CLI_LIMITS.datasetRows.maximum}>              Defaults to ${CLI_LIMITS.datasetRows.default}
+  --offset <n>                  Non-negative; defaults to 0
+
+\`list\` and \`get\` show a dataset's schema, its latest version, and the syncs and pipelines you
+may run that read or write it. \`versions\` lists the newest first. \`rows\` leaves out the
+columns your clearances do not cover and names them under redactions.`,
+  syncs: `Usage:
+  sixb syncs list
+  sixb syncs get <sync-id>
+
+Lists the syncs you may run, each with its latest run. \`sixb sync-runs list\` shows the history.`,
+  "sync-runs": `Usage:
+  sixb sync-runs list [options]
+
+List options:
+  --sync <sync-id>
+  --dataset <dataset-id>
+  --status queued|running|succeeded|failed|cancelled
+  --started-after|--started-before <RFC3339>
+  --limit <1-${CLI_LIMITS.list.maximum}>              Defaults to ${CLI_LIMITS.list.default}
+  --offset <n>                  Non-negative; defaults to 0
+  --order <asc|desc>            Started-time order; defaults to ${DEFAULT_LIST_ORDER}`,
+  pipelines: `Usage:
+  sixb pipelines list
+  sixb pipelines get <pipeline-id>
+
+Lists the pipelines you may run, each with its latest run. \`sixb pipeline-runs\` shows the
+history and each run's steps.`,
+  "pipeline-runs": `Usage:
+  sixb pipeline-runs list [options]
+  sixb pipeline-runs get <run-id>
+
+List options:
+  --pipeline <pipeline-id>
+  --status queued|running|succeeded|failed|cancelled
+  --started-after|--started-before <RFC3339>
+  --limit <1-${CLI_LIMITS.list.maximum}>              Defaults to ${CLI_LIMITS.list.default}
+  --offset <n>                  Non-negative; defaults to 0
+  --order <asc|desc>            Started-time order; defaults to ${DEFAULT_LIST_ORDER}
+
+\`get\` includes the run's steps.`,
 } as const
 
 export const QUERY_EXAMPLES: Readonly<Record<string, string>> = {

package/src/commands/models.ts

@@ -4,7 +4,7 @@ import type { ApiClient } from "../api-client"
 import { enumValue, integerInRange, isHelp, parseCommandArgs, requestsHelp } from "../arguments"
 import { fail, writeJson, writeText } from "../output"
 import { GROUP_HELP } from "./metadata"
-import { readText } from "./shared"
+import { idSegment, readText } from "./shared"
 
 export const MODEL_KINDS = ["language", "image", "speech", "transcription"] as const
 export type ModelKind = (typeof MODEL_KINDS)[number]
@@ -277,7 +277,7 @@ async function calls(api: ApiClient, args: readonly string[]): Promise<void> {
     1
   )
   const callId = positionals[0] ?? ""
-  const call = (await api.get(`/api/ai/model-calls/${encodeURIComponent(callId)}/files`)) as {
+  const call = (await api.get(`/api/ai/model-calls/${idSegment(callId)}/files`)) as {
     readonly callId: string
     readonly files: readonly FileRef[]
   }
@@ -390,7 +390,7 @@ async function saveFiles(
   })
   for (const [index, path] of paths.entries()) {
     await mkdir(dirname(path), { recursive: true })
-    await api.download(`/api/ai/model-calls/${encodeURIComponent(callId)}/files/content`, path, {
+    await api.download(`/api/ai/model-calls/${idSegment(callId)}/files/content`, path, {
       path: `/files/${index}`,
     })
   }

package/src/commands/ontology.ts

@@ -2,7 +2,7 @@ import type { ApiClient } from "../api-client"
 import { isHelp, parseCommandArgs, requestsHelp } from "../arguments"
 import { fail, writeJson, writeText } from "../output"
 import { GROUP_HELP } from "./metadata"
-import { asRecord, asRecords, vectorProfileNames } from "./shared"
+import { asRecord, asRecords, idSegment, vectorProfileNames } from "./shared"
 
 export async function ontology(api: ApiClient, args: readonly string[]): Promise<void> {
   const [sub, ...rest] = args
@@ -46,7 +46,7 @@ export async function ontology(api: ApiClient, args: readonly string[]): Promise
   if (sub === "get") {
     if (requestsHelp(rest)) return writeText("Usage: sixb ontology get <object-type>")
     const { positionals } = parseCommandArgs(rest, {}, "ontology get", 1)
-    return writeJson(await api.get(`/api/object-types/${encodeURIComponent(positionals[0] ?? "")}`))
+    return writeJson(await api.get(`/api/object-types/${idSegment(positionals[0])}`))
   }
   fail(`Unknown ontology command '${sub}'.`)
 }

package/src/commands/runs.ts

@@ -21,16 +21,33 @@ const WORKFLOW_RUN_STATUSES = [
   "failed",
   "cancelled",
 ] as const
+const DATA_RUN_STATUSES = ["queued", "running", "succeeded", "failed", "cancelled"] as const
+
+const STATUSES = {
+  action: ACTION_RUN_STATUSES,
+  workflow: WORKFLOW_RUN_STATUSES,
+  sync: DATA_RUN_STATUSES,
+  pipeline: DATA_RUN_STATUSES,
+} as const
+
+/** The list filters each kind adds to the common window, by flag and query parameter. */
+const FILTERS = {
+  action: { "--action": "actionId", "--type": "objectTypeId", "--id": "primaryId" },
+  workflow: { "--workflow": "workflowId" },
+  sync: { "--sync": "syncId", "--dataset": "datasetId" },
+  pipeline: { "--pipeline": "pipelineId" },
+} as const
 
 export async function runs(
   api: ApiClient,
-  kind: "action" | "workflow",
+  kind: keyof typeof STATUSES,
   args: readonly string[]
 ): Promise<void> {
   const [sub, ...rest] = args
-  const group = `${kind}-runs` as "action-runs" | "workflow-runs"
+  const group = `${kind}-runs` as const
   if (!sub || isHelp(sub) || requestsHelp(rest)) return writeText(GROUP_HELP[group])
-  if (sub === "get") {
+  // The API lists sync runs but has no route for one.
+  if (sub === "get" && kind !== "sync") {
     const { positionals } = parseCommandArgs(rest, {}, `${group} get`, 1)
     return writeJson(await api.get(`/api/${group}/${encodeURIComponent(positionals[0] ?? "")}`))
   }
@@ -43,15 +60,8 @@ export async function runs(
       "--offset": "offset",
       "--order": "order",
     }
-    const action = {
-      ...common,
-      "--action": "actionId",
-      "--type": "objectTypeId",
-      "--id": "primaryId",
-    }
-    const workflow = { ...common, "--workflow": "workflowId" }
     const options = normalizeWindowOptions(
-      parseQueryOptions(rest, kind === "action" ? action : workflow, `${group} list`),
+      parseQueryOptions(rest, { ...common, ...FILTERS[kind] }, `${group} list`),
       {
         defaultLimit: CLI_LIMITS.list.default,
         maximumLimit: CLI_LIMITS.list.maximum,
@@ -60,11 +70,7 @@ export async function runs(
       }
     )
     if (options.status !== undefined) {
-      options.status = enumValue(
-        "--status",
-        options.status,
-        kind === "action" ? ACTION_RUN_STATUSES : WORKFLOW_RUN_STATUSES
-      )
+      options.status = enumValue("--status", options.status, STATUSES[kind])
     }
     for (const [name, flag] of [
       ["startedAfter", "--started-after"],

package/src/commands/shared.ts

@@ -4,6 +4,12 @@ import { fail } from "../output"
 
 export type QueryOptions = Record<string, string | undefined>
 
+/** An id as one segment of an API path: `.` or `..` would name another route. */
+export function idSegment(value: string | undefined): string {
+  if (!value || value === "." || value === "..") fail(`'${value ?? ""}' is not an id.`)
+  return encodeURIComponent(value)
+}
+
 /** Parse flag/value pairs into API query parameters. */
 
 export function parseQueryOptions(