@frontera-sdk/cli 0.1.0 → 1.43.5

package/src/commands/blueprint/grants.ts

@@ -0,0 +1,164 @@
+import { BlueprintAuthoringApi } from '../../api/blueprint-authoring-api'
+import { CliError } from '../../errors'
+import type { Command, CommandContext } from '../types'
+
+/**
+ * Who may read which object types.
+ *
+ * Addressed by NAME rather than id, because an organization key holds no workspace
+ * and the ids are not otherwise discoverable from a terminal — the whole point of the
+ * `org-workspaces` and `org-agents` reads, which the lane already opens. An ambiguous
+ * name is an error listing the candidates: guessing which of two workspaces called
+ * "Ops" was meant is a guess about who can read the Blueprint.
+ */
+
+function api(ctx: CommandContext): BlueprintAuthoringApi {
+  return new BlueprintAuthoringApi(ctx.apiUrl, ctx.token)
+}
+
+async function resolveSubject(
+  client: BlueprintAuthoringApi,
+  subject: 'workspace' | 'agent',
+  nameOrId: string,
+): Promise<{ id: string; name: string }> {
+  const candidates = subject === 'workspace' ? await client.orgWorkspaces() : await client.orgAgents()
+  const byId = candidates.find((candidate) => candidate.id === nameOrId)
+  if (byId?.id) return { id: byId.id, name: byId.name ?? byId.id }
+
+  const matches = candidates.filter((candidate) =>
+    candidate.name === nameOrId
+    || (subject === 'workspace' && (candidate as { slug?: string }).slug === nameOrId))
+  const only = matches.length === 1 ? matches[0] : undefined
+  if (only?.id) return { id: only.id, name: only.name ?? only.id }
+  if (matches.length > 1) {
+    throw new CliError(
+      `"${nameOrId}" names ${matches.length} ${subject}s in this organization.`,
+      {
+        code: 'USAGE',
+        hint: `Use the id: ${matches.map((match) => match.id).join(', ')}`,
+      },
+    )
+  }
+  throw new CliError(`No ${subject} named "${nameOrId}" in this organization.`, {
+    code: 'NOT_FOUND',
+    hint: candidates.length
+      ? `Known ${subject}s: ${candidates.map((candidate) => candidate.name).filter(Boolean).join(', ')}`
+      : `No ${subject}s are visible to this credential.`,
+  })
+}
+
+export const blueprintGrant: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'grant',
+    args: [
+      { name: 'subject', required: true, description: 'workspace | agent | list' },
+      { name: 'name', required: false, description: 'Workspace or agent, by name or id' },
+      { name: 'apiName...', required: false, description: 'One or more object type API names' },
+    ],
+    flags: { revoke: 'boolean' },
+    summary: 'Grant or revoke an object type for a workspace or an agent',
+    examples: [
+      'frontera blueprint grant workspace Ops Customer Policy',
+      'frontera blueprint grant agent "Claims bot" Customer --revoke',
+      'frontera blueprint grant list',
+    ],
+  },
+  async run(ctx) {
+    const client = api(ctx)
+    const [subject, name, ...apiNames] = ctx.positional
+
+    if (subject === 'list') {
+      const workspaces = await client.orgWorkspaces()
+      const agents = await client.orgAgents()
+      const rows: Array<{
+        subject: string
+        name: string
+        granted: string[]
+        unreadable?: string
+      }> = []
+      /**
+       * A subject the key cannot read is REPORTED, not fatal.
+       *
+       * Grants are workspace- and agent-addressed, so a key whose workspace list omits
+       * one is refused for that row alone. Failing the whole listing because a single
+       * subject is out of scope would hide every subject that IS in scope — and the
+       * out-of-scope ones are exactly what the reader needs to see to understand why.
+       */
+      const readGrants = async (
+        subject: 'workspace' | 'agent',
+        id: string,
+        name: string,
+      ) => {
+        try {
+          const grants = subject === 'workspace'
+            ? await client.workspaceGrants(id)
+            : await client.agentGrants(id)
+          rows.push({
+            subject,
+            name,
+            granted: grants.map((grant) => grant.objectTypeApiName ?? '').filter(Boolean),
+          })
+        } catch (err) {
+          const forbidden = err instanceof CliError && err.code === 'FORBIDDEN'
+          if (!forbidden) throw err
+          rows.push({
+            subject,
+            name,
+            granted: [],
+            unreadable: `not in this key's ${subject} list`,
+          })
+        }
+      }
+
+      for (const workspace of workspaces) {
+        if (workspace.id) await readGrants('workspace', workspace.id, workspace.name ?? workspace.id)
+      }
+      for (const agent of agents) {
+        if (agent.id) await readGrants('agent', agent.id, agent.name ?? agent.id)
+      }
+      const text = rows.length === 0
+        ? 'No workspaces or agents are visible to this credential.'
+        : rows
+          .map((row) => `${row.subject} ${row.name}: `
+            + (row.unreadable ? `— ${row.unreadable}` : row.granted.join(', ') || '(none)'))
+          .join('\n')
+      return { data: rows, text }
+    }
+
+    if (subject !== 'workspace' && subject !== 'agent') {
+      throw new CliError(
+        `Unknown subject "${subject ?? ''}". Expected workspace, agent or list.`,
+        { code: 'USAGE', hint: 'frontera blueprint grant --help' },
+      )
+    }
+    if (!name) {
+      throw new CliError(`A ${subject} name or id is required.`, {
+        code: 'USAGE',
+        hint: `frontera blueprint grant ${subject} <name> <apiName…>`,
+      })
+    }
+    if (apiNames.length === 0) {
+      throw new CliError('At least one object type apiName is required.', {
+        code: 'USAGE',
+        hint: `frontera blueprint grant ${subject} ${name} Customer`,
+      })
+    }
+
+    const resolved = await resolveSubject(client, subject, name)
+    const revoke = ctx.flags.revoke === true
+    for (const apiName of apiNames) {
+      if (subject === 'workspace') {
+        if (revoke) await client.revokeWorkspace(resolved.id, apiName)
+        else await client.grantWorkspace(resolved.id, apiName)
+      } else if (revoke) await client.revokeAgent(resolved.id, apiName)
+      else await client.grantAgent(resolved.id, apiName)
+    }
+
+    return {
+      data: { subject, id: resolved.id, name: resolved.name, apiNames, revoked: revoke },
+      text: `${revoke ? 'Revoked' : 'Granted'} ${apiNames.join(', ')} `
+        + `${revoke ? 'from' : 'to'} ${subject} "${resolved.name}".`,
+    }
+  },
+}

package/src/commands/dataset/index-commands.ts

@@ -0,0 +1,431 @@
+import { readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+
+import { DatasetApi, type DatasetColumn } from '../../api/dataset-api'
+import { CliError } from '../../errors'
+import { table } from '../../table'
+import type { Command } from '../types'
+
+/**
+ * Datasets — the source contract a Blueprint object type reads.
+ *
+ * `blueprint bind` names a dataset, and `backing.dataset` in a committed tree names one
+ * too. Until this noun existed the CLI could author everything that REFERRED to a
+ * dataset and nothing that CREATED one, so standing up an organization always broke at
+ * the same step: open the Console, make the dataset by hand, come back.
+ *
+ * All three forms the Console offers are here, chosen by `kind` in the definition file
+ * rather than by three verbs: they differ in where the COLUMNS come from, and nothing
+ * else. `blank` declares them, `source` reads them from a relation on a connected
+ * Source, `file` reads them from a CSV.
+ *
+ * `blank` is the only one a committed tree can fully describe, and the only one a
+ * Blueprint binding strictly needs. The other two are here because an FDE has to be
+ * able to do them without the Console, not because a tree can hold them: a Source is
+ * made elsewhere and a CSV's bytes live outside the tree by nature, so both are named
+ * rather than inlined.
+ */
+
+const COLUMN_TYPES = ['text', 'numeric', 'boolean', 'date', 'timestamptz'] as const
+
+/** Same rule the service enforces, checked here to save a round trip. */
+const IDENTIFIER = /^[a-z_][a-z0-9_]*$/
+
+interface DatasetFile {
+  kind?: unknown
+  apiName?: unknown
+  displayName?: unknown
+  description?: unknown
+  columns?: unknown
+  keyColumns?: unknown
+  deterministicKeyConfirmed?: unknown
+  /** `source` only. */
+  source?: unknown
+  schema?: unknown
+  relation?: unknown
+  /** `source` and `file`. */
+  includedColumns?: unknown
+  /** `file` only — a path, relative to the definition file's own directory. */
+  path?: unknown
+}
+
+function names(raw: unknown, field: string, path: string): string[] {
+  if (!Array.isArray(raw) || raw.length === 0 || raw.some((n) => typeof n !== 'string' || !n)) {
+    throw new CliError(`${path} needs a non-empty \`${field}\` list of column names.`, {
+      code: 'USAGE',
+      hint: `frontera dataset preview ./file.csv lists what a CSV holds; frontera dataset sources lists Sources.`,
+    })
+  }
+  return raw as string[]
+}
+
+function readColumns(raw: unknown, path: string): DatasetColumn[] {
+  if (!Array.isArray(raw) || raw.length === 0) {
+    throw new CliError(`${path} declares no \`columns\`.`, {
+      code: 'USAGE',
+      hint: 'columns: [{ name, databaseType, nullable }] — at least one.',
+    })
+  }
+  return raw.map((entry, position) => {
+    const where = `${path}: columns[${position}]`
+    if (!entry || typeof entry !== 'object') {
+      throw new CliError(`${where} is not a mapping.`, {
+        code: 'USAGE',
+        hint: 'Each column is { name, databaseType, nullable }.',
+      })
+    }
+    const column = entry as Record<string, unknown>
+    const name = column.name
+    if (typeof name !== 'string' || !IDENTIFIER.test(name)) {
+      throw new CliError(`${where} has an unusable \`name\`.`, {
+        code: 'USAGE',
+        // Named rather than normalised: silently lowercasing a column would produce a
+        // contract that does not match the source it is supposed to describe.
+        hint: 'A column name is lower_snake_case: a letter or underscore, then letters, digits, underscores.',
+      })
+    }
+    const databaseType = column.databaseType
+    if (typeof databaseType !== 'string' || !COLUMN_TYPES.includes(databaseType as never)) {
+      throw new CliError(`${where} has an unknown \`databaseType\`.`, {
+        code: 'USAGE',
+        hint: `One of: ${COLUMN_TYPES.join(', ')}`,
+      })
+    }
+    if (typeof column.nullable !== 'boolean') {
+      throw new CliError(`${where} does not say whether it is \`nullable\`.`, {
+        code: 'USAGE',
+        // Not defaulted: `required` on a Blueprint property is enforced against this,
+        // and guessing it wrong is discovered at bind time or not at all.
+        hint: 'nullable: true or false. A Blueprint `required` property may not read a nullable column carrying nulls.',
+      })
+    }
+    return { name, databaseType, nullable: column.nullable } as DatasetColumn
+  })
+}
+
+const list: Command = {
+  meta: {
+    noun: 'dataset',
+    verb: 'list',
+    args: [],
+    flags: {},
+    summary: 'List the datasets this organization can bind an object type to',
+    examples: ['frontera dataset list', 'frontera dataset list --json'],
+  },
+  async run(ctx) {
+    const rows = await new DatasetApi(ctx.apiUrl, ctx.token).list()
+    return {
+      data: rows,
+      text: rows.length === 0
+        ? 'No datasets in this organization.'
+        : table(
+            ['apiName', 'displayName', 'id'],
+            rows.map((row) => [row.apiName ?? row.name ?? '?', row.displayName ?? '', row.id ?? '']),
+            [30, 30, undefined],
+          ),
+    }
+  },
+}
+
+const get: Command = {
+  meta: {
+    noun: 'dataset',
+    verb: 'get',
+    args: [{ name: 'apiName', required: true, description: 'The dataset’s API name' }],
+    flags: {},
+    summary: 'Show a dataset and the column contract of its current revision',
+    examples: ['frontera dataset get customers'],
+  },
+  async run(ctx) {
+    const apiName = ctx.positional[0]
+    if (!apiName) {
+      throw new CliError('A dataset apiName is required.', {
+        code: 'USAGE',
+        hint: 'frontera dataset list',
+      })
+    }
+    const api = new DatasetApi(ctx.apiUrl, ctx.token)
+    const datasets = await api.list()
+    const dataset = datasets.find((entry) => (entry.apiName ?? entry.name) === apiName)
+    if (!dataset?.id) {
+      throw new CliError(`No dataset named "${apiName}" in this organization.`, {
+        code: 'NOT_FOUND',
+        // The empty case reads as "missing" and is usually a capability, not a fact.
+        hint: datasets.length === 0
+          ? 'No datasets are visible at all — the key may have been minted without dataset:read.'
+          : `Visible: ${datasets.map((entry) => entry.apiName ?? entry.name).filter(Boolean).join(', ')}`,
+      })
+    }
+    const revisions = await api.revisions(dataset.id)
+    const current = revisions.find((entry) => entry.id === dataset.currentRevisionId) ?? revisions.at(-1)
+    return {
+      data: { dataset, revision: current },
+      text: [
+        `${apiName} — ${dataset.displayName ?? ''}`.trim(),
+        current?.columns?.length
+          ? table(
+              ['column', 'type', 'nullable'],
+              current.columns.map((column) => [
+                column.name ?? '?', column.databaseType ?? '?', String(column.nullable ?? ''),
+              ]),
+            )
+          : 'No published revision yet — nothing can bind to it.',
+      ].join('\n'),
+    }
+  },
+}
+
+const sources: Command = {
+  meta: {
+    noun: 'dataset',
+    verb: 'sources',
+    args: [],
+    flags: {},
+    summary: 'List the connected Sources a dataset can be pulled from',
+    examples: ['frontera dataset sources'],
+  },
+  async run(ctx) {
+    const rows = await new DatasetApi(ctx.apiUrl, ctx.token).listSources()
+    return {
+      data: rows,
+      text: rows.length === 0
+        ? 'No Sources in this organization. A Source is connected in the Console.'
+        : table(
+            ['displayName', 'type', 'status', 'id'],
+            rows.map((row) => [
+              row.displayName ?? '?', row.connectorType ?? '', row.status ?? '', row.id ?? '',
+            ]),
+          ),
+    }
+  },
+}
+
+const preview: Command = {
+  meta: {
+    noun: 'dataset',
+    verb: 'preview',
+    args: [{ name: 'path', required: true, description: 'Path to a CSV' }],
+    flags: {},
+    summary: 'Read a CSV’s columns without creating anything',
+    examples: ['frontera dataset preview ./customers.csv'],
+  },
+  async run(ctx) {
+    const path = ctx.positional[0]
+    if (!path) {
+      throw new CliError('A path to a CSV is required.', {
+        code: 'USAGE',
+        hint: 'frontera dataset preview ./customers.csv',
+      })
+    }
+    // The file form has to declare `includedColumns`, and nobody can write that list
+    // before seeing what the CSV holds. This is that step, and it creates nothing.
+    const result = await new DatasetApi(ctx.apiUrl, ctx.token)
+      .uploadPreview(resolve(ctx.cwd, path))
+    const columns = result.columns ?? []
+    return {
+      data: result,
+      text: [
+        `${columns.length} column${columns.length === 1 ? '' : 's'}, ${result.rowCount ?? 0} rows`,
+        table(
+          ['column', 'type', 'nullable'],
+          columns.map((c) => [c.name ?? '?', c.databaseType ?? '?', String(c.nullable ?? '')]),
+        ),
+      ].join('\n'),
+    }
+  },
+}
+
+const testSource: Command = {
+  meta: {
+    noun: 'dataset',
+    verb: 'test-source',
+    args: [{ name: 'source', required: true, description: 'The Source’s displayName' }],
+    flags: {},
+    summary: 'Verify a Source can be reached, which `kind: source` requires',
+    examples: ['frontera dataset test-source "Local Postgres"'],
+  },
+  async run(ctx) {
+    const name = ctx.positional[0]
+    if (!name) {
+      throw new CliError('A Source displayName is required.', {
+        code: 'USAGE',
+        hint: 'frontera dataset sources',
+      })
+    }
+    const api = new DatasetApi(ctx.apiUrl, ctx.token)
+    const source = (await api.listSources()).find((entry) => entry.displayName === name)
+    const revisionId = source?.currentRevision?.id
+    if (!revisionId) {
+      throw new CliError(`No Source named "${name}", or it has no current revision.`, {
+        code: 'NOT_FOUND',
+        hint: 'frontera dataset sources',
+      })
+    }
+    // A separate verb rather than something `create` does implicitly: this opens a
+    // connection to somebody else's database, and a command that reaches the network
+    // as a side effect of reading a file is a command nobody can predict.
+    const result = await api.testSourceRevision(revisionId)
+    // A test that could not connect still answers 200 — the verdict is in the body, and
+    // reading only the status code reported "reachable" for a refused connection, which
+    // then surfaced as an unexplained CONFLICT at `create`.
+    const test = result.latestConnectionTest ?? result
+    if (test.status !== 'verified') {
+      throw new CliError(
+        `"${name}" could not be reached: ${test.errorMessage ?? test.status ?? 'unknown'}.`,
+        {
+          code: 'FAILURE',
+          hint: test.errorCode === 'NETWORK_DENIED'
+            // Worth naming: a private or loopback address is refused unless the
+            // deployment explicitly permits that path, which reads as a broken Source.
+            ? 'The adapter refused the address. A private or loopback host needs the deployment to permit it explicitly.'
+            : `frontera dataset sources — the Source is registered but its connection failed (${test.errorCode ?? 'no code'}).`,
+        },
+      )
+    }
+    return {
+      data: { source: name, revisionId, test },
+      text: `"${name}" is reachable. It can now back a dataset: frontera dataset create --file <kind: source>`,
+    }
+  },
+}
+
+const create: Command = {
+  meta: {
+    noun: 'dataset',
+    verb: 'create',
+    args: [],
+    flags: { file: 'string' },
+    aliases: { f: 'file' },
+    summary: 'Create a dataset — from declared columns, a Source relation, or a CSV',
+    examples: [
+      'frontera dataset create --file ./customers.json',
+    ],
+  },
+  async run(ctx) {
+    const filePath = ctx.flags.file as string | undefined
+    if (!filePath) {
+      throw new CliError('A dataset definition is required: pass --file <file>.', {
+        code: 'USAGE',
+        hint: 'The file names a `kind`: blank, source, or file.',
+      })
+    }
+    const path = resolve(ctx.cwd, filePath)
+    const document = JSON.parse(readFileSync(path, 'utf8')) as DatasetFile
+
+    const apiName = document.apiName
+    if (typeof apiName !== 'string' || !apiName) {
+      throw new CliError(`${filePath} names no \`apiName\`.`, {
+        code: 'USAGE',
+        hint: 'apiName is how `backing.dataset` and `blueprint bind` refer to it.',
+      })
+    }
+    const displayName = typeof document.displayName === 'string' && document.displayName
+      ? document.displayName
+      : apiName
+    const description = typeof document.description === 'string'
+      ? { description: document.description }
+      : {}
+
+    const keyColumns = document.keyColumns === undefined || document.keyColumns === null
+      ? null
+      : document.keyColumns
+    if (keyColumns !== null && !Array.isArray(keyColumns)) {
+      throw new CliError(`${filePath} has \`keyColumns\` that is neither a list nor null.`, {
+        code: 'USAGE',
+        hint: 'keyColumns: ["id"] for a keyed dataset, or null when no column identifies a row.',
+      })
+    }
+    // Only ever true when the file DECLARED key columns. The flag attests that the key
+    // identifies a row uniquely, and attesting that of a key nobody named is a claim
+    // the file never made.
+    const deterministicKeyConfirmed = document.deterministicKeyConfirmed === true && keyColumns !== null
+    const common = {
+      apiName,
+      displayName,
+      ...description,
+      keyColumns: keyColumns as string[] | null,
+      deterministicKeyConfirmed,
+    }
+
+    const api = new DatasetApi(ctx.apiUrl, ctx.token)
+    const kind = document.kind ?? 'blank'
+    let created
+
+    if (kind === 'blank') {
+      const columns = readColumns(document.columns, filePath)
+      const declared = new Set(columns.map((column) => column.name))
+      for (const key of (keyColumns ?? []) as string[]) {
+        if (!declared.has(key)) {
+          throw new CliError(`${filePath}: keyColumns names "${key}", which is not a declared column.`, {
+            code: 'USAGE',
+            hint: `Declared: ${[...declared].join(', ')}`,
+          })
+        }
+      }
+      created = await api.createBlank({ ...common, columns })
+    } else if (kind === 'source') {
+      const sourceName = document.source
+      if (typeof sourceName !== 'string' || !sourceName) {
+        throw new CliError(`${filePath} names no \`source\`.`, {
+          code: 'USAGE',
+          hint: 'frontera dataset sources — the file names one by displayName, never by id.',
+        })
+      }
+      // Named, not id'd: a Source id is minted per deployment, so a definition
+      // carrying one would be correct here and wrong in the next organization —
+      // the same reason nothing in a Blueprint tree carries a uuid.
+      const all = await api.listSources()
+      const source = all.find((entry) => entry.displayName === sourceName)
+      if (!source?.id) {
+        throw new CliError(`No Source named "${sourceName}" in this organization.`, {
+          code: 'NOT_FOUND',
+          hint: all.length === 0
+            ? 'No Sources are visible — a Source is connected in the Console, and reading them needs dataSource:read.'
+            : `Visible: ${all.map((entry) => entry.displayName).filter(Boolean).join(', ')}`,
+        })
+      }
+      const schema = document.schema
+      const relation = document.relation
+      if (typeof schema !== 'string' || !schema || typeof relation !== 'string' || !relation) {
+        throw new CliError(`${filePath} needs both \`schema\` and \`relation\`.`, {
+          code: 'USAGE',
+          hint: 'The relation this dataset pulls, e.g. schema: public, relation: customers.',
+        })
+      }
+      created = await api.createFromSource({
+        ...common,
+        sourceId: source.id,
+        schema,
+        relation,
+        includedColumns: names(document.includedColumns, 'includedColumns', filePath),
+      })
+    } else if (kind === 'file') {
+      const csv = document.path
+      if (typeof csv !== 'string' || !csv) {
+        throw new CliError(`${filePath} names no \`path\` to a CSV.`, {
+          code: 'USAGE',
+          hint: 'path is resolved relative to the definition file, so the pair can move together.',
+        })
+      }
+      // Relative to the DEFINITION, not the shell's cwd: the two travel together in a
+      // repo, and resolving against cwd broke the moment anyone ran it from elsewhere.
+      created = await api.createFromFile(
+        resolve(dirname(path), csv),
+        { ...common, includedColumns: names(document.includedColumns, 'includedColumns', filePath) },
+      )
+    } else {
+      throw new CliError(`${filePath} has an unknown \`kind\`: ${String(kind)}.`, {
+        code: 'USAGE',
+        hint: 'One of: blank, source, file.',
+      })
+    }
+
+    return {
+      data: created,
+      text: `Created dataset "${apiName}". `
+        + `Bind an object type to it: frontera blueprint bind <ObjectType> --dataset ${apiName} --plan ./map.json`,
+    }
+  },
+}
+
+export const datasetCommands: Command[] = [list, get, sources, preview, testSource, create]