@sixb/cli-core 0.1.4

package/src/arguments.ts

@@ -0,0 +1,130 @@
+import { fail } from "./output"
+
+type OptionKinds = Readonly<Record<string, "string" | "boolean">>
+
+/** Parse a command's options once, before reading files or calling the API. */
+export function parseCommandArgs<const T extends OptionKinds>(
+  args: readonly string[],
+  kinds: T,
+  command: string,
+  positionalCount: number | readonly [number, number] = 0
+): {
+  positionals: string[]
+  options: { [K in keyof T]?: T[K] extends "boolean" ? boolean : string }
+} {
+  const positionals: string[] = []
+  const options: Record<string, string | boolean> = {}
+  let positionalOnly = false
+  for (let index = 0; index < args.length; index++) {
+    const argument = args[index] ?? ""
+    if (!positionalOnly && argument === "--") {
+      positionalOnly = true
+      continue
+    }
+    if (positionalOnly || !argument.startsWith("-") || argument === "-") {
+      positionals.push(argument)
+      continue
+    }
+    const equals = argument.indexOf("=")
+    const flag = equals < 0 ? argument : argument.slice(0, equals)
+    if (!Object.hasOwn(kinds, flag)) fail(`Unknown ${command} option '${flag}'.`)
+    if (Object.hasOwn(options, flag)) fail(`${flag} may only be provided once.`)
+    if (kinds[flag] === "boolean") {
+      if (equals >= 0) fail(`${flag} does not accept a value.`)
+      options[flag] = true
+    } else {
+      const value = equals < 0 ? args[++index] : argument.slice(equals + 1)
+      if (!value || (equals < 0 && value.startsWith("--"))) {
+        fail(`${flag} requires a value.`)
+      }
+      options[flag] = value
+    }
+  }
+  const [minimum, maximum] =
+    typeof positionalCount === "number" ? [positionalCount, positionalCount] : positionalCount
+  if (positionals.length < minimum || positionals.length > maximum) {
+    fail(`Invalid arguments for '${command}'.`)
+  }
+  return {
+    positionals,
+    // Every assigned option was checked against its declared kind above.
+    options: options as { [K in keyof T]?: T[K] extends "boolean" ? boolean : string },
+  }
+}
+
+export function requestsHelp(args: readonly string[]): boolean {
+  const separator = args.indexOf("--")
+  const beforeSeparator = separator < 0 ? args : args.slice(0, separator)
+  return isHelp(args[0]) || beforeSeparator.includes("--help") || beforeSeparator.includes("-h")
+}
+
+/** Argument validation shared by every instance command mode. */
+
+const RFC3339_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/
+
+export function isHelp(value: string | undefined): boolean {
+  return value === "-h" || value === "--help" || value === "help"
+}
+
+export function requireExact(args: readonly string[], count: number, message: string): void {
+  if (args.length !== count) fail(message)
+}
+
+export function integerInRange(
+  flag: string,
+  value: string,
+  minimum: number,
+  maximum: number
+): number {
+  if (!/^[0-9]+$/.test(value)) {
+    fail(`${flag} must be an integer from ${minimum} through ${maximum}.`)
+  }
+  const parsed = Number(value)
+  if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum) {
+    fail(`${flag} must be an integer from ${minimum} through ${maximum}.`)
+  }
+  return parsed
+}
+
+export function nonNegativeInteger(flag: string, value: string): number {
+  if (!/^[0-9]+$/.test(value)) {
+    fail(`${flag} must be a non-negative integer.`)
+  }
+  const parsed = Number(value)
+  if (!Number.isSafeInteger(parsed)) {
+    fail(`${flag} must be a non-negative safe integer.`)
+  }
+  return parsed
+}
+
+export function rfc3339Value(flag: string, value: string): string {
+  if (!RFC3339_TIMESTAMP.test(value) || Number.isNaN(Date.parse(value))) {
+    fail(`${flag} must be an RFC 3339 timestamp.`)
+  }
+  return value
+}
+
+export function requireOrderedRange(
+  afterFlag: string,
+  after: string | undefined,
+  beforeFlag: string,
+  before: string | undefined
+): void {
+  if (after && before && Date.parse(after) > Date.parse(before)) {
+    fail(`${afterFlag} must be before or equal to ${beforeFlag}.`)
+  }
+}
+
+export function enumValue<const T extends readonly string[]>(
+  flag: string,
+  value: string,
+  allowed: T
+): T[number] {
+  if (!allowed.includes(value)) fail(`${flag} must be ${formatAlternatives(allowed)}.`)
+  return value as T[number]
+}
+
+function formatAlternatives(values: readonly string[]): string {
+  if (values.length < 2) return values[0] ?? "a supported value"
+  return `${values.slice(0, -1).join(", ")}, or ${values.at(-1)}`
+}

package/src/commands/actions.ts

@@ -0,0 +1,94 @@
+import type { ApiClient } from "../api-client"
+import { isHelp, parseCommandArgs, requestsHelp } from "../arguments"
+import { CliError, EXIT_API, fail, writeJson, writeText } from "../output"
+import { GROUP_HELP } from "./metadata"
+import { asRecord, parseQueryOptions, readJson } from "./shared"
+
+export async function actions(api: ApiClient, args: readonly string[]): Promise<void> {
+  const [sub, ...rest] = args
+  if (!sub || isHelp(sub) || requestsHelp(rest)) return writeText(GROUP_HELP.actions)
+  if (sub === "get") {
+    const { positionals } = parseCommandArgs(rest, {}, "actions get", 1)
+    return writeJson(await api.get(`/api/actions/${encodeURIComponent(positionals[0] ?? "")}`))
+  }
+  if (sub === "list") {
+    const options = parseQueryOptions(rest, { "--type": "objectTypeId" }, "actions list")
+    const response = await api.get("/api/actions")
+    if (!options.objectTypeId) return writeJson(response)
+    if (!Array.isArray(response)) fail("The actions API returned an invalid response.")
+    return writeJson(
+      response.filter((value) => asRecord(value).objectTypeId === options.objectTypeId)
+    )
+  }
+  if (sub === "request") {
+    const { positionals, options } = parseCommandArgs(
+      rest,
+      {
+        "--subject-type": "string",
+        "--subject-id": "string",
+        "--file": "string",
+        "--run-id": "string",
+        "--wait": "boolean",
+      },
+      "actions request",
+      1
+    )
+    const actionId = positionals[0] ?? ""
+    const subjectType = options["--subject-type"]
+    const subjectId = options["--subject-id"]
+    const paramsSource = options["--file"]
+    const runId = options["--run-id"]
+    const wait = options["--wait"]
+    if (Boolean(subjectType) !== Boolean(subjectId)) {
+      fail("--subject-type and --subject-id must be provided together.")
+    }
+    const params = paramsSource ? await readJson(paramsSource) : {}
+    if (Array.isArray(params) || typeof params !== "object" || params === null) {
+      fail("Action params must be a JSON object.")
+    }
+    const requested = await api.post(`/api/actions/${encodeURIComponent(actionId)}`, {
+      params,
+      ...(subjectType && subjectId
+        ? { subject: { kind: "object", objectTypeId: subjectType, primaryId: subjectId } }
+        : {}),
+      ...(runId ? { runId } : {}),
+    })
+    if (!wait) return writeJson(requested)
+
+    const requestedRunId = asRecord(requested).runId
+    if (typeof requestedRunId !== "string" || requestedRunId.length === 0) {
+      throw new CliError(
+        {
+          code: "invalid_api_response",
+          message: "The Action request response did not contain a run id.",
+        },
+        EXIT_API
+      )
+    }
+    return writeJson(await waitForActionRun(api, requestedRunId))
+  }
+  fail(`Unknown actions command '${sub}'.`)
+}
+
+const ACTION_WAIT_TIMEOUT_MS = 25_000
+const ACTION_WAIT_POLL_MS = 250
+const TERMINAL_ACTION_STATUSES = new Set(["succeeded", "failed", "cancelled"])
+
+async function waitForActionRun(api: ApiClient, runId: string): Promise<unknown> {
+  const startedAt = Date.now()
+  while (Date.now() - startedAt < ACTION_WAIT_TIMEOUT_MS) {
+    const run = await api.get(`/api/action-runs/${encodeURIComponent(runId)}`)
+    const status = asRecord(run).status
+    if (typeof status === "string" && TERMINAL_ACTION_STATUSES.has(status)) return run
+    await new Promise((resolve) => setTimeout(resolve, ACTION_WAIT_POLL_MS))
+  }
+
+  throw new CliError(
+    {
+      code: "action_wait_timeout",
+      message: `Action run '${runId}' did not finish within ${ACTION_WAIT_TIMEOUT_MS / 1_000} seconds.`,
+      hint: `Inspect it with 'sixb action-runs get ${runId}'.`,
+    },
+    EXIT_API
+  )
+}

package/src/commands/files.ts

@@ -0,0 +1,52 @@
+import { access } from "node:fs/promises"
+import type { ApiClient } from "../api-client"
+import { isHelp, parseCommandArgs, requestsHelp, requireExact } from "../arguments"
+import { fail, writeJson, writeText } from "../output"
+import { GROUP_HELP } from "./metadata"
+
+export async function files(api: ApiClient, args: readonly string[]): Promise<void> {
+  const [sub, ...rest] = args
+  if (!sub || isHelp(sub) || requestsHelp(rest)) return writeText(GROUP_HELP.files)
+  if (sub === "upload") {
+    const { positionals, options } = parseCommandArgs(
+      rest,
+      { "--logical-path": "string" },
+      "files upload",
+      1
+    )
+    const source = positionals[0] ?? ""
+    try {
+      await access(source)
+    } catch {
+      fail(`Upload file '${source}' does not exist.`)
+    }
+    return writeJson(await api.upload("/api/files", source, options["--logical-path"]))
+  }
+  if (sub === "download") {
+    const { positionals, options } = parseCommandArgs(
+      rest,
+      { "--path": "string", "--output": "string" },
+      "files download",
+      [2, 3]
+    )
+    const context = positionals[0]
+    let route: string
+    if (context === "object") {
+      requireExact(positionals, 3, "files download object requires object type and primary id.")
+      const type = positionals[1] ?? ""
+      const id = positionals[2] ?? ""
+      route = `/api/objects/${encodeURIComponent(type)}/${encodeURIComponent(id)}/files/content`
+    } else if (context === "action-run" || context === "workflow-run") {
+      requireExact(positionals, 2, `files download ${context} requires exactly one run id.`)
+      const id = positionals[1] ?? ""
+      route = `/api/${context}s/${encodeURIComponent(id)}/files/content`
+    } else fail(`Unknown file download context '${context}'.`)
+    const path = options["--path"]
+    const output = options["--output"]
+    if (!path) fail("files download requires --path <json-pointer>.")
+    if (!output) fail("files download requires --output <local-path>.")
+    await api.download(route, output, { path })
+    return writeJson({ downloaded: true, output })
+  }
+  fail(`Unknown files command '${sub}'.`)
+}

package/src/commands/index.ts

@@ -0,0 +1,57 @@
+import type { ApiClient } from "../api-client"
+import { fail } from "../output"
+import { actions } from "./actions"
+import { files } from "./files"
+import { objects } from "./objects"
+import { ontology } from "./ontology"
+import { project } from "./project"
+import { runs } from "./runs"
+import { telemetry } from "./telemetry"
+import { workflows } from "./workflows"
+
+export const INSTANCE_COMMANDS = [
+  "project",
+  "ontology",
+  "objects",
+  "telemetry",
+  "actions",
+  "action-runs",
+  "files",
+  "workflows",
+  "workflow-runs",
+] as const
+
+export type InstanceCommand = (typeof INSTANCE_COMMANDS)[number]
+
+export function isInstanceCommand(command: string): command is InstanceCommand {
+  return (INSTANCE_COMMANDS as readonly string[]).includes(command)
+}
+
+export async function dispatch(
+  api: ApiClient,
+  command: string,
+  args: readonly string[]
+): Promise<void> {
+  switch (command) {
+    case "project":
+      return project(api, args)
+    case "ontology":
+      return ontology(api, args)
+    case "objects":
+      return objects(api, args)
+    case "telemetry":
+      return telemetry(api, args)
+    case "actions":
+      return actions(api, args)
+    case "action-runs":
+      return runs(api, "action", args)
+    case "files":
+      return files(api, args)
+    case "workflows":
+      return workflows(api, args)
+    case "workflow-runs":
+      return runs(api, "workflow", args)
+    default:
+      fail(`Unknown command '${command}'. Run 'sixb --help'.`)
+  }
+}

package/src/commands/metadata.ts

@@ -0,0 +1,212 @@
+import {
+  CLI_LIMITS,
+  DEFAULT_LIST_ORDER,
+  DEFAULT_OBJECT_ORDER_BY,
+  DEFAULT_TELEMETRY_ORDER,
+} from "../policies"
+
+const SANDBOX_MAIN_HELP = `Sixb agent CLI
+
+Usage:
+  sixb <command> [options]
+
+The CLI uses the run-scoped SIXB_API_BASE_URL. 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 context                        Print the current run context
+  sixb project show                   Show project metadata
+  sixb ontology list                  Compact visible type and relationship catalog
+  sixb ontology get <type>            Inspect one object type, properties, links, and actions
+
+Objects:
+  sixb objects inspect <type> <id>    Inspect an object and its related graph in one command
+  sixb objects list [options]         Browse materialized objects
+  sixb objects get <type> <id>...     Exact lookup through opaque object references
+  sixb objects search <text>          Search visible objects
+  sixb objects query --file <file|->  Execute query IR from JSON
+  sixb objects count --file <file|->  Count a query without returning rows
+  sixb objects exists --file <file|-> Test whether a query has a match
+  sixb objects facets --file <file|-> Run a {query, facets} request
+  sixb objects links <type> <id>      Read exact persisted links
+
+Telemetry:
+  sixb telemetry latest <type> <id> <property>
+  sixb telemetry history <type> <id> <property> [options]
+  sixb telemetry query --file <file|->
+
+Actions and workflows:
+  sixb actions list|get|request ...
+  sixb action-runs list|get ...
+  sixb workflows list|get|start ...
+  sixb workflow-runs list|get ...
+
+Files:
+  sixb files upload|download ...
+
+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",
+    ""
+  )
+
+export function renderInstanceHelp(mode: "local" | "sandbox"): string {
+  return mode === "sandbox" ? SANDBOX_MAIN_HELP : LOCAL_MAIN_HELP
+}
+
+export const OBJECTS_HELP = `Usage:
+  sixb objects inspect <object-type> <primary-id> [options]
+  sixb objects list [options]
+  sixb objects get <object-type> <primary-id>...
+  sixb objects search <text> [--limit <1-${CLI_LIMITS.search.maximum}>]
+  sixb objects query --file <path|-> [--include-total|--no-total]
+  sixb objects query --example <name>
+  sixb objects count --file <path|->
+  sixb objects exists --file <path|->
+  sixb objects facets --file <path|->
+  sixb objects facets --example
+  sixb objects links <object-type> <primary-id> [options]
+
+List options:
+  --type <id>                         Exact ontology object type id
+  --limit <1-${CLI_LIMITS.list.maximum}>                    Defaults to ${CLI_LIMITS.list.default}
+  --offset <n>                        Non-negative; defaults to 0
+  --order-by createdAt|updatedAt|primaryId  Defaults to ${DEFAULT_OBJECT_ORDER_BY}
+  --order asc|desc                    Defaults to ${DEFAULT_LIST_ORDER}
+  --id-prefix <value>                 Primary-id prefix
+  --id-suffix <value>                 Primary-id suffix
+  --created-after|--created-before <RFC3339>
+  --updated-after|--updated-before <RFC3339>
+
+Links options:
+  --link <link-id>
+  --direction outgoing|incoming|both  Defaults to both
+  --page-size <1-${CLI_LIMITS.linkPage.maximum}>                Defaults to ${CLI_LIMITS.linkPage.default}
+  --page-token <token>                Continue an edge page
+  --include-objects                   Include selected and current-page endpoint objects
+
+Inspect options:
+  --depth <0-${CLI_LIMITS.inspect.depth.maximum}>                       Defaults to ${CLI_LIMITS.inspect.depth.default}; use 0 for only the object
+  --max-objects <1-${CLI_LIMITS.inspect.objects.maximum}>               Defaults to ${CLI_LIMITS.inspect.objects.default}
+  --max-links <1-${CLI_LIMITS.inspect.links.maximum}>                 Defaults to ${CLI_LIMITS.inspect.links.default}
+  --full                              Include timestamps and encountered type definitions
+
+Use \`objects get\` first when context provides an exact object reference. Use \`objects inspect\`
+only when related objects are needed; it follows both relationship directions to depth 2 by
+default and returns a bounded graph.
+Inspect omits materialization timestamps and ontology definitions by default. Use \`--full\` when
+storage timestamps, declared links, or available actions are needed.
+
+Search returns at most ${CLI_LIMITS.search.maximum} matches and defaults to ${CLI_LIMITS.search.default}.
+
+\`objects get\` uses a refs query without identity URL paths. Opaque ids containing :, /, #, ?, or
+% are safe. Identifiers are case-sensitive.`
+
+export const QUERY_HELP = `Usage:
+  sixb objects query --file <path|-> [--include-total|--no-total]
+  sixb objects query --example <exact|filter|incoming|expand|sort|page>
+  sixb objects query --example list
+
+Input is a query node. A full {"query": ...} request is also accepted.
+
+Query nodes compose through input:
+  start     {"kind":"start","objectTypeId":"Type","includeSubtypes":false}
+  refs      {"kind":"refs","refs":[{"objectTypeId":"Type","primaryId":"opaque:id"}]}
+  filter    {"kind":"filter","input":<query>,"predicate":<predicate>}
+  text      {"kind":"text","input":<query>,"query":"words","fields":["name"]}
+  traverse  {"kind":"traverse","input":<query>,"linkId":"link","direction":"outgoing"}
+  vector, set, sort, limit, page, project, and expand are also supported.
+
+Predicates use op, not kind:
+  and/or, not, {"op":"eq","propertyId":"status","value":"open"}, neq, lt, lte, gt, gte,
+  in, exists, and contains.
+
+Traversal and expansion directions are outgoing or incoming. For incoming relationships, the link
+is declared on the child/source type; add sourceObjectTypeId when needed to disambiguate it.
+
+Run \`sixb ontology get <type>\` first; never guess property or link ids. Use refs for exact
+identities. Put limits and pages inside the query tree.`
+
+export const GROUP_HELP = {
+  doctor: "Usage: sixb doctor",
+  context: "Usage: sixb context",
+  project: "Usage: sixb project show",
+  ontology: `Usage:
+  sixb ontology list [--full]
+  sixb ontology get <object-type>`,
+  telemetry: `Usage:
+  sixb telemetry latest <object-type> <primary-id> <property-id>
+  sixb telemetry history <object-type> <primary-id> <property-id> [options]
+  sixb telemetry query --file <path|->
+
+History options:
+  --from <RFC3339>
+  --to <RFC3339>
+  --limit <1-${CLI_LIMITS.telemetryHistory.maximum}>                  Defaults to ${CLI_LIMITS.telemetryHistory.default}
+  --order <asc|desc>                  Timestamp order; defaults to ${DEFAULT_TELEMETRY_ORDER}`,
+  actions: `Usage:
+  sixb actions list [--type <object-type>]
+  sixb actions get <action-id>
+  sixb actions request <action-id> [--subject-type <type> --subject-id <id>] [--file <path|->] [--run-id <id>] [--wait]
+
+\`actions get\` includes inputSchema, the exact JSON shape accepted by the Action. The JSON file
+contains that parameter object; use - to read standard input. --wait returns the terminal Action
+run and waits at most 25 seconds.`,
+  "action-runs": `Usage:
+  sixb action-runs list [options]
+  sixb action-runs get <run-id>
+
+List options:
+  --action <action-id>
+  --type <object-type>
+  --id <primary-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}`,
+  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>`,
+  workflows: `Usage:
+  sixb workflows list
+  sixb workflows get <workflow-id>
+  sixb workflows start <workflow-id> [--file <path|->]
+
+The JSON file contains the workflow input object. Use - to read standard input.`,
+  "workflow-runs": `Usage:
+  sixb workflow-runs list [options]
+  sixb workflow-runs get <run-id>
+
+List options:
+  --workflow <workflow-id>
+  --status queued|running|waiting|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}`,
+} as const
+
+export const QUERY_EXAMPLES: Readonly<Record<string, string>> = {
+  exact:
+    '{"kind":"refs","refs":[{"objectTypeId":"RepositoryIssue","primaryId":"github:issue:owner/repo#297"}]}',
+  filter: `{"kind":"limit","input":{"kind":"filter","input":{"kind":"start","objectTypeId":"Customer"},"predicate":{"op":"eq","propertyId":"status","value":"active"}},"limit":${CLI_LIMITS.list.default}}`,
+  incoming:
+    '{"kind":"traverse","input":{"kind":"refs","refs":[{"objectTypeId":"RepositoryIssue","primaryId":"github:issue:owner/repo#297"}]},"linkId":"issue","direction":"incoming","sourceObjectTypeId":"RepositoryComment"}',
+  expand: `{"kind":"expand","input":{"kind":"refs","refs":[{"objectTypeId":"RepositoryIssue","primaryId":"github:issue:owner/repo#297"}]},"expansions":[{"linkId":"issue","direction":"incoming","sourceObjectTypeId":"RepositoryComment","limit":${CLI_LIMITS.list.default}}]}`,
+  sort: `{"kind":"limit","input":{"kind":"sort","input":{"kind":"start","objectTypeId":"Customer"},"fields":[{"kind":"property","propertyId":"name","direction":"asc"}]},"limit":${CLI_LIMITS.list.default}}`,
+  page: `{"kind":"page","input":{"kind":"start","objectTypeId":"Customer"},"pageSize":${CLI_LIMITS.list.default}}`,
+}
+
+export const FACETS_EXAMPLE =
+  '{"query":{"kind":"start","objectTypeId":"WorkOrder"},"facets":[{"propertyId":"status","limit":10}]}'