@frontera-sdk/cli 0.1.0 → 1.43.5

package/src/blueprint/projection.ts

@@ -0,0 +1,254 @@
+import { CliError } from '../errors'
+import {
+  ARTIFACT_KINDS,
+  KIND_DIRECTORY,
+  type AuthoredFile,
+  type AuthoredModel,
+  type BundleObject,
+  type BundleRelationship,
+  type DefinitionBundle,
+  type LiveIndex,
+} from './model'
+
+/**
+ * The one place the file format and the definition bundle are translated.
+ *
+ * Nothing else may translate. A second translation site is how a projection stops
+ * being total — one side learns about a field and the other does not, and `pull`
+ * quietly drops it, and the next `apply` deletes it from the draft.
+ *
+ * Both directions are here so they can be read as a pair and tested as one:
+ * `fromFiles(toFiles(bundle))` compiles back to `bundle`.
+ */
+
+/** Fields the projection resolves rather than copies. Never written to a file. */
+const OBJECT_RESOLVED = new Set([
+  'id',
+  'primaryKeyPropertyId',
+  'titlePropertyId',
+  'properties',
+  'governance',
+])
+
+const LINK_RESOLVED = new Set([
+  'id',
+  'fromObjectId',
+  'toObjectId',
+  'fromPropertyId',
+  'toPropertyId',
+  'fromDisplayName',
+  'toDisplayName',
+  'fromPhrase',
+  'toPhrase',
+  'datasetBacking',
+])
+
+function rest(source: Record<string, unknown>, resolved: Set<string>): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(source)) {
+    if (!resolved.has(key)) out[key] = value
+  }
+  return out
+}
+
+/**
+ * A property entry, with its shared field named rather than identified.
+ *
+ * The wire's `sharedPropertyId` is the one uuid a property carries that HAS a name
+ * to resolve to, so it is resolved rather than stripped — a file that kept it would
+ * be unportable in the precise sense this whole tree exists to avoid. The authored
+ * key is `sharedField`: the tree is what a person writes, and a person writes field.
+ *
+ * An id the bundle does not declare is a corrupt export, and it fails here rather
+ * than writing the uuid: a tree that round-trips a per-deployment identifier reads
+ * as portable and is not, and the failure would then appear at the second
+ * deployment instead of at the `pull` that produced it.
+ */
+function propertyToFile(
+  property: Record<string, unknown>,
+  objectApiName: string,
+  sharedApiNameById: Map<string, string>,
+): Record<string, unknown> {
+  const body = rest(property, new Set(['id', 'sharedPropertyId']))
+  const sharedPropertyId = property.sharedPropertyId
+  if (sharedPropertyId === undefined || sharedPropertyId === null) return body
+  const apiName = sharedApiNameById.get(String(sharedPropertyId))
+  if (!apiName) {
+    throw new CliError(
+      `Field "${String(property.apiName)}" on ${objectApiName} references shared field `
+      + `${String(sharedPropertyId)}, which this draft does not declare.`,
+      {
+        code: 'FAILURE',
+        hint: 'The draft is inconsistent — re-read it, and report it if it persists. '
+          + 'Writing the identifier into the file would make the tree unportable.',
+      },
+    )
+  }
+  return { ...body, sharedField: apiName }
+}
+
+/**
+ * `governance.sourceMappings[0]` → the portable `backing:` a file writes.
+ *
+ * The dataset NAME, never the revision id: the name means the same thing in two
+ * deployments and the revision it points at does not. Emitted only when a name is
+ * resolvable — `diff` calls `toFiles` without a resolver precisely so that backings
+ * do not enter the comparison, because `bind` owns them and `apply` must not try to.
+ */
+function backingToFile(
+  object: BundleObject,
+  datasetNameByRevisionId: Map<string, string> | undefined,
+): Record<string, unknown> | undefined {
+  if (!datasetNameByRevisionId) return undefined
+  const mapping = object.governance.sourceMappings[0] as {
+    datasetRevisionId?: string
+    propertyMappings?: Array<{ propertyId: string; sourcePath: string; sourceField?: string | null }>
+    editableProperties?: string[]
+  } | undefined
+  if (!mapping?.datasetRevisionId) return undefined
+  const dataset = datasetNameByRevisionId.get(mapping.datasetRevisionId)
+  if (!dataset) return undefined
+  const apiNameById = new Map(object.properties.map((property) => [property.id, property.apiName]))
+  const entries: Record<string, unknown> = {}
+  for (const entry of mapping.propertyMappings ?? []) {
+    const apiName = apiNameById.get(entry.propertyId)
+    if (!apiName) continue
+    entries[apiName] = entry.sourceField
+      ? { column: entry.sourcePath, field: entry.sourceField }
+      : entry.sourcePath
+  }
+  const editable = (mapping.editableProperties ?? [])
+    .map((id) => apiNameById.get(id))
+    .filter((name): name is string => Boolean(name))
+  return {
+    dataset,
+    mapping: entries,
+    ...(editable.length ? { editable } : {}),
+  }
+}
+
+function objectToFile(
+  object: BundleObject,
+  sharedApiNameById: Map<string, string>,
+  datasetNameByRevisionId?: Map<string, string>,
+): Record<string, unknown> {
+  const byId = new Map(object.properties.map((property) => [property.id, property.apiName]))
+  const backing = backingToFile(object, datasetNameByRevisionId)
+  return {
+    ...rest(object, OBJECT_RESOLVED),
+    // `governance.sourceMappings` is the binding, which `bind` owns. Everything else
+    // in governance — ownership, sensitivity — is authored, so it stays.
+    governance: rest(object.governance, new Set(['sourceMappings'])),
+    ...(backing ? { backing } : {}),
+    primaryKey: byId.get(object.primaryKeyPropertyId) ?? object.primaryKeyPropertyId,
+    title: byId.get(object.titlePropertyId) ?? object.titlePropertyId,
+    properties: object.properties.map((property) =>
+      propertyToFile(property, object.apiName, sharedApiNameById)),
+  }
+}
+
+function linkToFile(link: BundleRelationship, objectApiNameById: Map<string, string>, propertyApiNameById: Map<string, string>): Record<string, unknown> {
+  const endpoint = (
+    objectId: string,
+    propertyId: string,
+    displayName: unknown,
+    phrase: unknown,
+  ) => ({
+    objectType: objectApiNameById.get(objectId) ?? objectId,
+    property: propertyApiNameById.get(propertyId) ?? propertyId,
+    ...(displayName === undefined ? {} : { displayName }),
+    ...(phrase === undefined ? {} : { phrase }),
+  })
+  return {
+    ...rest(link, LINK_RESOLVED),
+    from: endpoint(link.fromObjectId, link.fromPropertyId, link.fromDisplayName, link.fromPhrase),
+    to: endpoint(link.toObjectId, link.toPropertyId, link.toDisplayName, link.toPhrase),
+  }
+}
+
+/**
+ * Live draft → the file tree a person edits. Lossless but for the resolved ids.
+ *
+ * `datasetNameByRevisionId` turns each object's pinned revision back into the dataset
+ * name a file can carry. `pull` supplies it; `diff` does not, and that asymmetry is
+ * deliberate — see `backingToFile`.
+ */
+export function toFiles(
+  bundle: DefinitionBundle,
+  datasetNameByRevisionId?: Map<string, string>,
+): AuthoredModel {
+  const objectApiNameById = new Map(bundle.objects.map((object) => [object.id, object.apiName]))
+  const propertyApiNameById = new Map(
+    bundle.objects.flatMap((object) => object.properties.map((p) => [p.id, p.apiName] as const)),
+  )
+  const sharedApiNameById = new Map(
+    (bundle.sharedProperties ?? []).map((shared) => [shared.id, shared.apiName]),
+  )
+  const files: AuthoredFile[] = []
+  const push = (kind: AuthoredFile['kind'], apiName: string, document: Record<string, unknown>) => {
+    files.push({ kind, apiName, path: `${KIND_DIRECTORY[kind]}/${apiName}.yaml`, document })
+  }
+
+  for (const shared of bundle.sharedProperties ?? []) {
+    // A shared field owns no backing and references nothing, so stripping its id
+    // is the whole projection: what is left is portable as it stands.
+    push('shared-field', shared.apiName, rest(shared, new Set(['id'])))
+  }
+  for (const object of bundle.objects) {
+    push('object-type', object.apiName, objectToFile(object, sharedApiNameById, datasetNameByRevisionId))
+  }
+  for (const link of bundle.relationships) {
+    push('link-type', link.apiName, linkToFile(link, objectApiNameById, propertyApiNameById))
+  }
+  for (const metric of bundle.metrics) {
+    // A metric names the type it measures by `objectId`. Stripping only `id` left that
+    // uuid in the file — unportable, and unusable besides: the create route takes an
+    // `objectTypeApiName`, so a pulled metric could never be applied anywhere.
+    const { id: _id, objectId, ...body } = metric as Record<string, unknown> & { objectId?: string }
+    push('metric', metric.apiName, {
+      ...body,
+      ...(typeof objectId === 'string'
+        ? { objectType: objectApiNameById.get(objectId) ?? objectId }
+        : {}),
+    })
+  }
+
+  return { schemaVersion: bundle.schemaVersion, files: files.sort(byPath) }
+}
+
+function byPath(left: AuthoredFile, right: AuthoredFile): number {
+  return left.path.localeCompare(right.path)
+}
+
+/**
+ * The file tree, grouped by kind, ready for the compiler.
+ *
+ * This does not resolve anything — resolution needs the live draft, which a pure
+ * read of the tree does not have. See `compile.ts`.
+ */
+export function fromFiles(files: AuthoredFile[], schemaVersion: number): AuthoredModel {
+  return { schemaVersion, files: [...files].sort(byPath) }
+}
+
+export function filesOfKind(model: AuthoredModel, kind: AuthoredFile['kind']): AuthoredFile[] {
+  return model.files.filter((file) => file.kind === kind)
+}
+
+/** Every kind, in a fixed order, so callers never depend on tree iteration order. */
+export function kinds(): readonly AuthoredFile['kind'][] {
+  return ARTIFACT_KINDS
+}
+
+/**
+ * Does this bundle's schema version carry actions?
+ *
+ * v1 has no `actions` key at all and its schema is strict, so emitting an empty
+ * array would make a v1 bundle unparseable. The absence is meaningful.
+ */
+export function carriesActions(schemaVersion: number): boolean {
+  return schemaVersion >= 2
+}
+
+export function liveObject(index: LiveIndex, apiName: string): BundleObject | undefined {
+  return index.objectByApiName.get(apiName)
+}

package/src/blueprint/render.ts

@@ -0,0 +1,73 @@
+import type { ModelOperation, Plan } from './diff'
+
+/**
+ * The plan, as a person reads it.
+ *
+ * One line per artifact, marker first, so a long plan scans vertically. `--json`
+ * emits the `Plan` itself and never this text — the two must not drift, which is why
+ * the renderer takes the plan rather than being fed by the executor.
+ */
+
+const MARKER: Record<ModelOperation['operation'], string> = {
+  create: '+',
+  update: '~',
+  delete: '-',
+}
+
+function pad(value: string, width: number): string {
+  return value.length >= width ? value : value + ' '.repeat(width - value.length)
+}
+
+export function renderPlan(plan: Plan, options: { prune: boolean } = { prune: false }): string {
+  const rows: Array<{ marker: string; kind: string; apiName: string; detail: string }> = []
+
+  for (const operation of plan.operations) {
+    rows.push({
+      marker: MARKER[operation.operation],
+      kind: operation.kind,
+      apiName: operation.apiName,
+      detail: operation.detail ?? (operation.operation === 'create' ? 'create' : ''),
+    })
+  }
+  for (const operation of plan.prunes) {
+    rows.push({
+      marker: MARKER.delete,
+      kind: operation.kind,
+      apiName: operation.apiName,
+      // Naming the flag on the line rather than in a footnote: the reader is
+      // looking at the artifact they care about, not at the bottom of the output.
+      detail: options.prune ? 'delete' : 'delete — needs --prune, skipped',
+    })
+  }
+
+  if (rows.length === 0) {
+    return plan.unchanged === 0
+      ? 'No artifacts, and nothing to do.'
+      : `No changes. ${plan.unchanged} artifact${plan.unchanged === 1 ? ' matches' : 's match'} the draft.`
+  }
+
+  const kindWidth = Math.max(...rows.map((row) => row.kind.length))
+  const nameWidth = Math.max(...rows.map((row) => row.apiName.length))
+  const lines = rows.map((row) =>
+    `  ${row.marker} ${pad(row.kind, kindWidth)}  ${pad(row.apiName, nameWidth)}  ${row.detail}`.trimEnd(),
+  )
+
+  if (plan.unchanged > 0) {
+    lines.push(`  = ${plan.unchanged} unchanged`)
+  }
+  return lines.join('\n')
+}
+
+/** The `!` lines: a bound type whose dataset has moved to a different contract. */
+export function renderDrift(
+  drift: Array<{ objectApiName: string; datasetName: string; currentDigest: string }>,
+): string {
+  if (drift.length === 0) return ''
+  return drift
+    .map((entry) =>
+      `  ! binding  ${entry.objectApiName}  dataset \`${entry.datasetName}\` publishes a different `
+      + `column contract (${entry.currentDigest.slice(0, 14)}…)\n`
+      + `             re-review it: frontera blueprint bind ${entry.objectApiName} --dataset ${entry.datasetName} --plan <file>`,
+    )
+    .join('\n')
+}

package/src/blueprint/scaffold.ts

@@ -0,0 +1,79 @@
+import type { ArtifactKind } from './model'
+
+/**
+ * A starting file per kind, complete enough to apply as written once the placeholders
+ * are filled in.
+ *
+ * "Validates as written" is the bar, and it is not decoration: a scaffold missing a
+ * required field teaches the reader that the format is approximate, and the next
+ * thing they write omits three more. Every field the create route requires is here,
+ * including the ones with dull answers.
+ */
+export function scaffold(kind: ArtifactKind, apiName: string): Record<string, unknown> {
+  if (kind === 'object-type') {
+    return {
+      apiName,
+      displayName: apiName,
+      pluralDisplayName: `${apiName}s`,
+      // `primaryKey` and `title` name properties by apiName. The service resolves
+      // them to ids; nothing in this tree ever carries one.
+      primaryKey: 'id',
+      title: 'id',
+      governance: {
+        ownership: { kind: 'team', ownerId: 'blueprint-administration' },
+        sensitivity: { classification: 'internal', categories: [] },
+      },
+      properties: [{
+        apiName: 'id',
+        displayName: 'ID',
+        valueType: 'string',
+        required: true,
+        propertyType: 'attribute',
+      }],
+      validations: [],
+      // The dataset NAME, not a revision id: the name means the same thing in every
+      // deployment, and the revision it points at does not. One column per property,
+      // and no name-match fallback — the service refuses a mapping it was not given.
+      backing: {
+        dataset: 'CHANGE_ME',
+        mapping: { id: 'CHANGE_ME' },
+      },
+    }
+  }
+
+  if (kind === 'shared-field') {
+    // Identity and semantics, and nothing about where the data lives: no column,
+    // no `required`, no `unique`. `propertyType` is required — a shared field
+    // states how every implementing property is read — so it is written here
+    // with the commonest answer rather than left for the create route to refuse.
+    return {
+      apiName,
+      displayName: apiName,
+      description: 'CHANGE_ME',
+      valueType: 'string',
+      propertyType: 'attribute',
+    }
+  }
+
+  if (kind === 'link-type') {
+    return {
+      apiName,
+      cardinality: 'one_to_many',
+      from: { objectType: 'CHANGE_ME', property: 'id', displayName: 'CHANGE_ME', phrase: 'has' },
+      to: { objectType: 'CHANGE_ME', property: 'id', displayName: 'CHANGE_ME', phrase: 'belongs to' },
+    }
+  }
+
+  // A metric names the type it measures and the measures it computes. Both are
+  // required by the create route, so a scaffold without them would contradict this
+  // command's own promise that what it writes validates as written.
+  return {
+    apiName,
+    displayName: apiName,
+    objectType: 'CHANGE_ME',
+    definition: {
+      measures: [{ agg: 'count', label: 'Count' }],
+      dimensions: [],
+    },
+  }
+}

package/src/blueprint/tree.ts

@@ -0,0 +1,121 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, extname, join } from 'node:path'
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
+import { CliError } from '../errors'
+import {
+  ARTIFACT_KINDS,
+  DIRECTORY_KIND,
+  KIND_DIRECTORY,
+  type ArtifactKind,
+  type AuthoredFile,
+} from './model'
+
+/**
+ * Reading and writing the `blueprint/` tree. No network, no resolution.
+ *
+ * YAML and JSON are both accepted, chosen by extension, because a tree generated by
+ * another tool should not have to be converted before it can be applied. `pull` and
+ * `new` emit YAML: it diffs better in a pull request, which is the whole reason the
+ * Blueprint is in files.
+ */
+
+const READABLE = new Set(['.yaml', '.yml', '.json'])
+
+export function parseDocument(path: string, text: string): Record<string, unknown> {
+  const parsed = extname(path) === '.json' ? JSON.parse(text) : parseYaml(text)
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new CliError(`${path} does not contain a mapping.`, {
+      code: 'USAGE',
+      hint: 'Each file holds exactly one artifact, written as a mapping of fields.',
+    })
+  }
+  return parsed as Record<string, unknown>
+}
+
+/**
+ * Read the whole tree.
+ *
+ * A file whose `apiName` disagrees with its filename is an error rather than a
+ * rename: the two are the same identity written twice, and guessing which one the
+ * author meant is the difference between renaming an artifact and replacing it.
+ */
+export function readTree(root: string): AuthoredFile[] {
+  const files: AuthoredFile[] = []
+  for (const kind of ARTIFACT_KINDS) {
+    const directory = join(root, KIND_DIRECTORY[kind])
+    if (!existsSync(directory)) continue
+    for (const entry of readdirSync(directory).sort()) {
+      const extension = extname(entry)
+      if (!READABLE.has(extension)) continue
+      const relative = `${KIND_DIRECTORY[kind]}/${entry}`
+      const document = parseDocument(relative, readFileSync(join(directory, entry), 'utf8'))
+      const stem = entry.slice(0, -extension.length)
+      const apiName = document.apiName
+      if (typeof apiName !== 'string' || !apiName) {
+        throw new CliError(`${relative} declares no apiName.`, {
+          code: 'USAGE',
+          hint: `Add \`apiName: ${stem}\`, or delete the file.`,
+        })
+      }
+      if (apiName !== stem) {
+        throw new CliError(
+          `${relative} declares apiName "${apiName}", which is not its filename.`,
+          {
+            code: 'USAGE',
+            hint: `Renaming is an explicit act: \`frontera blueprint rename ${kind} ${stem} ${apiName}\`.`,
+          },
+        )
+      }
+      files.push({ kind, apiName, path: relative, document })
+    }
+  }
+  return files
+}
+
+/**
+ * Delete a file the tree should no longer contain.
+ *
+ * `writeTree` only ever wrote, which left `pull --force` keeping artifacts that had
+ * since left the draft — the next `plan` then reported a phantom create for something
+ * nobody had authored. "Two pulled trees are byte-identical" was true only of fresh
+ * directories.
+ */
+export function removeFromTree(root: string, paths: string[]): string[] {
+  const removed: string[] = []
+  for (const relative of paths) {
+    const absolute = join(root, relative)
+    if (!existsSync(absolute)) continue
+    rmSync(absolute)
+    removed.push(relative)
+  }
+  return removed
+}
+
+export function writeTree(root: string, files: AuthoredFile[]): string[] {
+  const written: string[] = []
+  for (const file of files) {
+    const absolute = join(root, file.path)
+    mkdirSync(dirname(absolute), { recursive: true })
+    writeFileSync(absolute, serialize(file.path, file.document))
+    written.push(file.path)
+  }
+  return written
+}
+
+export function serialize(path: string, document: Record<string, unknown>): string {
+  return extname(path) === '.json'
+    ? `${JSON.stringify(document, null, 2)}\n`
+    // `lineWidth: 0` disables wrapping. A wrapped description reflows the moment
+    // someone edits a word before it, which turns a one-word change into a
+    // multi-line diff and hides what actually changed.
+    : stringifyYaml(document, { lineWidth: 0 })
+}
+
+/** Which files a tree already holds, so `new` can refuse to overwrite one. */
+export function pathFor(kind: ArtifactKind, apiName: string): string {
+  return `${KIND_DIRECTORY[kind]}/${apiName}.yaml`
+}
+
+export function kindOfDirectory(directory: string): ArtifactKind | undefined {
+  return DIRECTORY_KIND[directory]
+}

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

@@ -86,6 +86,83 @@ async function readDocument(ctx: CommandContext): Promise<Record<string, unknown
   }
 }
 
+/** `agent_configs.agentId` — a slug, lowercase, the value every verb takes. */
+const SLUG_PATTERN = /^[a-z][a-z0-9-]*$/
+
+const create: Command = {
+  meta: {
+    noun: 'agent',
+    verb: 'create',
+    args: [
+      {
+        name: 'slug',
+        required: true,
+        description: 'lowercase slug every other agent command takes, e.g. claims-triage',
+      },
+    ],
+    flags: { name: 'string', description: 'string', kind: 'string' },
+    summary: 'Create an agent, ready for `agent apply` and `agent publish`',
+    examples: [
+      'frontera agent create claims-triage --name "Claims Triage"',
+      'frontera agent create nightly-extract --kind work',
+    ],
+  },
+  async run(ctx) {
+    const slug = ctx.positional[0]
+    if (!slug) {
+      throw new UsageError('missing <slug>', 'frontera agent create <slug> [--name <text>]')
+    }
+    if (!SLUG_PATTERN.test(slug)) {
+      throw new UsageError(
+        `"${slug}" is not a valid slug`,
+        'lowercase letters, digits and hyphens, starting with a letter — e.g. claims-triage',
+      )
+    }
+
+    const kind = flagString(ctx, 'kind')
+    if (kind && kind !== 'conversation' && kind !== 'work') {
+      throw new UsageError(`unknown --kind "${kind}"`, 'conversation (default) or work')
+    }
+
+    const client = api(ctx)
+
+    // Checked before the write: the service answers a duplicate slug from deep
+    // inside the create transaction, and the message names a constraint rather
+    // than the agent that already holds the name.
+    const existing = await client.agent(slug).catch((err: unknown) => {
+      if ((err as { code?: string }).code === 'NOT_FOUND') return null
+      throw err
+    })
+    if (existing) {
+      throw new CliError(`an agent with the slug "${slug}" already exists`, {
+        code: 'CONFLICT',
+        hint: `stage a change onto it with \`frontera agent apply ${slug} -f <file>\``,
+      })
+    }
+
+    const name = flagString(ctx, 'name')
+    const description = flagString(ctx, 'description')
+    const row = (await client.createAgent({
+      agentId: slug,
+      ...(name ? { name } : {}),
+      ...(description ? { description } : {}),
+      ...(kind ? { kind: kind as 'conversation' | 'work' } : {}),
+    })) as { data?: AgentRow } | AgentRow
+    const agent = ((row as { data?: AgentRow }).data ?? row) as AgentRow
+
+    return {
+      data: agent,
+      text: [
+        `created ${slug}${agent.id ? `  ${agent.id}` : ''}`,
+        // Said plainly because the next thing a caller does is run `agent list`,
+        // see nothing, and conclude the create failed.
+        `  it is in \`configuring\` and will NOT appear in \`frontera agent list\` until published`,
+        `  next: frontera agent apply ${slug} -f <file>  then  frontera agent publish ${slug}`,
+      ].join('\n'),
+    }
+  },
+}
+
 const list: Command = {
   meta: {
     noun: 'agent',
@@ -345,4 +422,13 @@ const versions: Command = {
   },
 }
 
-export const agentCommands: Command[] = [list, get, apply, publish, diff, discard, versions]
+export const agentCommands: Command[] = [
+  list,
+  get,
+  create,
+  apply,
+  publish,
+  diff,
+  discard,
+  versions,
+]