@frontera-sdk/cli 1.53.8 → 1.53.10

package/src/commands/blueprint/authoring.ts

@@ -9,6 +9,7 @@ import {
   migrationInstructions,
   newActionSteps,
   changedActionSteps,
+  needsActionSubjects,
   publishPlan,
 } from '../../blueprint/publish-plan'
 import { signInStep } from '../../device-login'
@@ -375,7 +376,11 @@ export const blueprintPublish: Command = {
       report = await client.validate()
     }
     const signIn = await signInStep({ profile: ctx.profile, apiUrl: ctx.apiUrl })
-    let plan = publishPlan(report, signIn, profile)
+    // An Action switched off by a change to its object type, not to itself, is found by its type.
+    const subjects = async (latest: ValidationReport) => (needsActionSubjects(latest)
+      ? new Map(((await client.draft()).definition.actions ?? []).map((action) => [action.id, String((action.subject as { objectTypeId?: unknown } | undefined)?.objectTypeId ?? '')]))
+      : undefined)
+    let plan = publishPlan(report, signIn, profile, await subjects(report))
 
     // What `action prepare` records, for each Action that has no decision yet.
     const prepared: string[] = []
@@ -385,7 +390,8 @@ export const blueprintPublish: Command = {
         await actions.recordDeploymentDecision(name, `Published with the Frontera CLI ("${label}"): ships switched off until a person deploys it and turns it on.`)
         prepared.push(name)
       }
-      plan = publishPlan(await client.validate(), signIn, profile)
+      const revalidated = await client.validate()
+      plan = publishPlan(revalidated, signIn, profile, await subjects(revalidated))
     }
     const preparedLines = prepared.map((name) => `Recorded that Action ${name} ships switched off: a person deploys it and turns it on after publish.`)
 
@@ -437,7 +443,12 @@ export const blueprintPublish: Command = {
       return { data: { release: released, prepared, newActions: [] }, text: `Release "${activeReleaseLabel}" is already active; nothing was published.` }
     }
     const newActions = plan.newActions.map((action) => ({ ...action, nextSteps: newActionSteps(action, signIn, profile) }))
-    const changedActions = plan.changedSwitchedOff.map((action) => ({ apiName: action.apiName, nextSteps: changedActionSteps(action, signIn, profile) }))
+    // An Action listed for its type's change is one this publish recorded switched off; one a person had switched off stays as they left it.
+    const listed = (action: { apiName: string; objectType?: string }) => !action.objectType || prepared.includes(action.apiName)
+    const changedActions = plan.changedSwitchedOff
+      .filter(listed)
+      .map((action) => ({ apiName: action.apiName, ...(action.objectType ? { objectType: action.objectType } : {}), nextSteps: changedActionSteps(action, signIn, profile) }))
+    const leftSwitchedOff = plan.changedSwitchedOff.filter((action) => !listed(action))
     const numbered = (steps: Array<{ step: string; command?: string }>) => steps.flatMap((step, index) => (step.command ? [`  ${index + 1}. ${step.step}:`, `       ${step.command}`] : [`  ${index + 1}. ${step.step}.`]))
     return {
       data: { release: released, prepared, newActions, changedActions },
@@ -451,9 +462,16 @@ export const blueprintPublish: Command = {
         ]),
         ...changedActions.flatMap((action) => [
           '',
-          `Action ${action.apiName} changed and is published switched off; its old write path does not run the new version. To turn it on again:`,
+          action.objectType
+            ? `Action ${action.apiName} acts on ${action.objectType}, which this release changes, and is published switched off; its old write path does not run it. To turn it on again:`
+            : `Action ${action.apiName} changed and is published switched off; its old write path does not run the new version. To turn it on again:`,
           ...numbered(action.nextSteps),
         ]),
+        ...leftSwitchedOff.flatMap((action) => [
+          '',
+          `Action ${action.apiName} acts on ${action.objectType}, which this release changes, and was switched off before this publish, so it stays switched off. `
+            + 'To run it on this release, `frontera action list` shows what it needs.',
+        ]),
       ].join('\n'),
     }
   },

package/src/commands/blueprint/declarative.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readdirSync } from 'node:fs'
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 
 import { BlueprintAuthoringApi } from '../../api/blueprint-authoring-api'
@@ -48,6 +48,7 @@ import {
   type DefinitionBundle,
 } from '../../blueprint/model'
 import { toFiles } from '../../blueprint/projection'
+import { namesOf, objectSetNamesOf, readPropertyIntents } from '../../blueprint/property-intents'
 import { sourceSystemHint } from '../../local/local-blueprint-errors'
 import { inheritedFromPull, unchangedSincePull } from '../../local/local-check-inherited'
 import { localProject } from '../../local/local-project'
@@ -63,7 +64,7 @@ import {
   type ScaffoldOptions,
   type SemanticTypeTemplate,
 } from '../../blueprint/scaffold'
-import { pathFor, readTree, removeFromTree, writeTree } from '../../blueprint/tree'
+import { pathFor, readObjectSets, readTree, removeFromTree, serialize, writeTree } from '../../blueprint/tree'
 import { CliError } from '../../errors'
 import type { Command, CommandContext } from '../types'
 
@@ -361,9 +362,9 @@ async function computePlan(ctx: CommandContext): Promise<{
       hint: 'frontera blueprint pull, or frontera blueprint new object-type <ApiName>',
     })
   }
-  const files = readTree(directory)
+  const authored = readTree(directory)
   // A measure's filters the draft would refuse: said by `plan`, and before `apply` writes anything.
-  const metricProblems = metricRuleProblems(files)
+  const metricProblems = metricRuleProblems(authored)
   if (metricProblems.length) {
     throw new CliError(`${metricProblems.length} metric problem${metricProblems.length === 1 ? '' : 's'} the draft would refuse, so nothing was planned or applied:\n${metricProblems.map((p) => `  ✕ ${p}`).join('\n')}`, {
       code: 'VALIDATION_ERROR',
@@ -372,8 +373,11 @@ async function computePlan(ctx: CommandContext): Promise<{
     })
   }
   const { definition, revision } = await client.draft()
+  // Compared against the draft as it reads once the files' renames are made, so a
+  // renamed property, and every file naming it, plans as the same property.
+  const { files, live, ...intents } = readPropertyIntents(authored, definition, readObjectSets(directory))
   const datasets = await readDatasetIndex(client, files, definition)
-  const plan = withheldPrunes(diff(files, definition, revision, datasets), directory)
+  const plan = withheldPrunes(diff(files, live, revision, datasets, intents), directory)
 
   // A type moving to another Dataset is no longer held to the old one's contract.
   const rebound = new Set(plan.rebind.map((change) => change.objectApiName))
@@ -635,6 +639,7 @@ export async function applyOperation(
       )
       current = nextRevision(updated, revision)
     }
+    current = await applyPropertyRenames(client, operation.apiName, operation.renames ?? [], current)
     current = await applyObjectKeys(client, operation.apiName, file, operation.liveDocument, current)
     current = await applyPropertyPlan(
       client, operation.apiName, file, operation.liveDocument, current, ids,
@@ -1012,10 +1017,8 @@ export function objectTypeMetadataChanges(
  * planning tool that says it did something it did not is the one failure worth
  * refusing outright, so anything this cannot map now aborts BEFORE the first write.
  *
- * Mapped: add, remove, and a change to any field the file can state. Unmapped: a
- * property rename, which is indistinguishable from a remove plus an add for the same
- * reason an object-type rename is (`rename` exists for that, and there is no
- * per-property equivalent).
+ * Mapped: add, remove, and a change to any field the file can state. A rename is
+ * made before this runs (`applyPropertyRenames`), so here it is the same property.
  */
 interface PropertyPlan {
   adds: Array<Record<string, unknown>>
@@ -1145,6 +1148,34 @@ function planProperties(
   return plan
 }
 
+/**
+ * A property that keeps its id and takes the name the file gives it (`renamedFrom`).
+ * Before the keys and the field commands, which name properties as the file does.
+ */
+async function applyPropertyRenames(
+  client: BlueprintAuthoringApi,
+  apiName: string,
+  renames: ReadonlyArray<{ from: string; to: string }>,
+  revision: number,
+): Promise<number> {
+  if (renames.length === 0) return revision
+  const detail = await client.getObjectTypeDetail(apiName)
+  let current = revision
+  for (const { from, to } of renames) {
+    const fieldId = detail?.properties.find((property) => property.apiName === from)?.id
+    if (!detail?.id || !fieldId) {
+      throw new CliError(`"${apiName}.${from}" is no longer on the draft.`, {
+        code: 'CONFLICT',
+        hint: 'frontera blueprint plan — the draft moved under this run.',
+      })
+    }
+    current = (await client.draftCommand({
+      kind: 'update_field_schema', objectId: detail.id, fieldId, patch: { apiName: to },
+    }, current)).revision
+  }
+  return current
+}
+
 async function applyPropertyPlan(
   client: BlueprintAuthoringApi,
   apiName: string,
@@ -1188,24 +1219,6 @@ async function applyPropertyPlan(
     }
   }
 
-  // A property that leaves AND one that arrives in the same edit is the shape a
-  // rename takes, and it is indistinguishable from a genuine replacement — the two
-  // have opposite consequences for the data behind the field. The earlier guard only
-  // caught it when `backing.mapping` lacked the new name; update the mapping too and
-  // it silently ran remove_field + add_field, which is the data drop the refusal was
-  // supposed to prevent.
-  if (plan.adds.length > 0 && plan.removes.length > 0) {
-    throw new CliError(
-      `${file.path}: this edit removes ${plan.removes.map((entry) => entry.apiName).join(', ')} and adds `
-      + `${plan.adds.map((entry) => String(entry.apiName)).join(', ')} at once.`,
-      {
-        code: 'USAGE',
-        hint: 'If that is a rename, there is no per-property rename command — do the removal and the '
-          + 'addition in separate applies, so the data consequence is a decision rather than a side effect.',
-      },
-    )
-  }
-
   let current = revision
   for (const property of plan.adds) {
     const name = String(property.apiName)
@@ -1376,6 +1389,13 @@ export const blueprintApply: Command = {
     const prune = ctx.flags.prune === true
     const { plan, files, definition, drift, actionProblems, inheritedWrites } = await computePlan(ctx)
     assertActionsApplicable(actionProblems, plan.operations)
+    if (plan.propertyRefusals?.length) {
+      // Said as a failed write says it, so `local dev` leaves that type off and applies the rest (`refusedArtifact`).
+      throw new CliError(`Nothing was applied.\nStopped at: update object-type ${plan.propertyRefusals[0]!.objectApiName}\n${plan.propertyRefusals.map((refusal) => refusal.message).join('\n')}`, {
+        code: 'USAGE',
+        hint: plan.propertyRefusals.map((refusal) => refusal.next).join('\n'),
+      })
+    }
     const actionWarnings = renderActionProblems({ refused: [], undeployable: actionProblems.undeployable, refusedActions: [], ...(actionProblems.inherited ? { inherited: actionProblems.inherited } : {}) })
 
     // BEFORE the first write, not before the prune loop: the operations land first,
@@ -1858,15 +1878,16 @@ export const blueprintRename: Command = {
     noun: 'blueprint',
     verb: 'rename',
     args: [
-      { name: 'kind', required: true, description: 'object-type' },
-      { name: 'from', required: true, description: 'Current apiName' },
+      { name: 'kind', required: true, description: 'object-type or property' },
+      { name: 'from', required: true, description: 'Current apiName (a property: its object type, then its current apiName)' },
       { name: 'to', required: true, description: 'New apiName' },
     ],
     flags: { dir: 'string' },
-    summary: 'Rename an object type, and its file, as one act',
-    examples: ['frontera blueprint rename object-type Client Customer'],
+    summary: 'Rename an object type or a property, and the files that name it, as one act',
+    examples: ['frontera blueprint rename object-type Client Customer', 'frontera blueprint rename property Ticket assignee owner'],
   },
   async run(ctx) {
+    if (ctx.positional[0] === 'property') return renameProperty(ctx)
     const [kind, from, to] = ctx.positional
     if (kind === 'object-type' && to && !API_NAME_RULE['object-type'].test(to)) {
       throw new CliError(`"${to}" is not a valid object-type apiName.`, {
@@ -1875,7 +1896,7 @@ export const blueprintRename: Command = {
       })
     }
     if (kind !== 'object-type') {
-      throw new CliError('Only object types can be renamed in place.', {
+      throw new CliError('Only object types and properties can be renamed in place.', {
         code: 'USAGE',
         // Being specific about the alternative rather than just refusing: for the
         // other kinds a delete-and-create is genuinely equivalent, because nothing
@@ -1929,6 +1950,93 @@ export const blueprintRename: Command = {
   },
 }
 
+/**
+ * `rename property <ObjectType> <from> <to>`: the same property under a new name,
+ * on the draft and in the files. The property keeps its id, so its column, its
+ * edited values and every Action, link and metric that names it stay with it, and
+ * the files that name it, saved object sets included, are changed to the new name. The type file keeps
+ * `renamedFrom: <from>` on it, which is how an apply or a change request against
+ * another draft that still has the old name renames it the same way.
+ */
+async function renameProperty(ctx: CommandContext) {
+  const [, objectApiName, from, to] = ctx.positional
+  if (!objectApiName || !from || !to) {
+    throw new CliError('A property rename names its object type, its current apiName and its new one.', {
+      code: 'USAGE',
+      hint: 'frontera blueprint rename property <ObjectType> <from> <to>',
+    })
+  }
+  if (!/^[a-z][A-Za-z0-9]{0,99}$/.test(to)) {
+    throw new CliError(`"${to}" is not a valid property apiName.`, { code: 'USAGE', hint: 'camelCase: a lowercase letter, then letters and digits, up to 100.' })
+  }
+  const client = api(ctx)
+  const detail = await client.getObjectTypeDetail(objectApiName)
+  if (!detail?.id) {
+    throw new CliError(`No object type "${objectApiName}" on the draft.`, { code: 'NOT_FOUND', hint: 'frontera blueprint catalog' })
+  }
+  const names = new Set(detail.properties.map((property) => property.apiName))
+  const field = detail.properties.find((property) => property.apiName === from)
+  if (field && names.has(to)) {
+    throw new CliError(`${objectApiName} has both ${from} and ${to}, so ${from} cannot take the name.`, {
+      code: 'CONFLICT',
+      hint: `remove ${to} first (its own apply), or rename ${from} to another name`,
+    })
+  }
+  if (!field && !names.has(to)) {
+    throw new CliError(`${objectApiName} has no property "${from}" on the draft.`, { code: 'NOT_FOUND', hint: `frontera blueprint get object-type ${objectApiName}` })
+  }
+  if (field?.id) {
+    await client.draftCommand(
+      { kind: 'update_field_schema', objectId: detail.id, fieldId: field.id, patch: { apiName: to } },
+      await client.revision(),
+    )
+  }
+
+  const directory = root(ctx)
+  const files = existsSync(directory) ? readTree(directory) : []
+  const changed = new Map<string, AuthoredFile>()
+  const changedSets: string[] = []
+  const typeFile = files.find((file) => file.kind === 'object-type' && file.apiName === objectApiName)
+  if (typeFile) {
+    const properties = Array.isArray(typeFile.document.properties) ? typeFile.document.properties as Array<Record<string, unknown>> : []
+    const target = properties.find((property) => property.apiName === to) ?? properties.find((property) => property.apiName === from)
+    if (target && (target.apiName !== to || target.renamedFrom !== from)) {
+      target.apiName = to
+      target.renamedFrom = from
+      changed.set(typeFile.path, typeFile)
+    }
+    // A property the file still names `from` is a new one taking the old name back,
+    // and what the files name `from` then means it.
+    if (!properties.some((property) => property.apiName === from)) {
+      for (const file of files) {
+        const places = namesOf(file, objectApiName, from)
+        for (const rename of places) rename(to)
+        if (places.length) changed.set(file.path, file)
+      }
+      const sets = readObjectSets(directory)
+      for (const set of sets) {
+        const places = objectSetNamesOf(set, files, sets, objectApiName, from)
+        for (const rename of places) rename(to)
+        if (places.length) {
+          writeFileSync(join(directory, set.path), serialize(set.path, set.document))
+          changedSets.push(set.path)
+        }
+      }
+    }
+  }
+  if (changed.size) writeTree(directory, [...changed.values()])
+  const changedPaths = [...changed.keys(), ...changedSets]
+  const where = changedPaths.length ? ` Changed ${changedPaths.join(', ')}.` : ''
+  return {
+    data: { objectType: objectApiName, from, to, renamedOnDraft: Boolean(field), changedFiles: changedPaths },
+    text: (field
+      ? `Renamed ${objectApiName}.${from} to ${to} on the draft. It keeps its id, so its column, its edited values and what names it stay with it.`
+      : `${objectApiName}.${from} is already ${to} on the draft.`)
+      + where
+      + '\nNext: `frontera blueprint apply --yes` applies the rest of the files, then `frontera blueprint publish` releases it.',
+  }
+}
+
 export const blueprintDeclarativeCommands: Command[] = [
   blueprintPull,
   blueprintPlan,

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

@@ -34,7 +34,7 @@ interface KnowledgeRow {
  */
 async function knowledgeAppNote(api: PlatformApi): Promise<string> {
   return (await api.knowledgeAppRuns())
-    ? ' A knowledge base from the Knowledge app is not one of these: it runs on the platform only, not on a local runtime. '
+    ? ' A knowledge base from the Knowledge app is not one of these: it runs on the platform only, with its search and AI answers, not on a local runtime. '
       + 'Choose it for an Agent on the platform, under the Agent\'s Knowledge page, and test that Agent there.'
     : ''
 }

package/src/commands/local/check.ts

@@ -28,6 +28,7 @@ import { findWorkflowTestFiles, recordWorkflowTestRun, runWorkflowTests, workflo
 import { vendoredSdkLine, vendoredSdkState } from '../../local/local-vendored-sdk'
 import { withFix } from '../../local/fix-words'
 import { runtimeKeyCustodianProblem } from '../../local/local-key-custodian'
+import { runtimeJobsProblem } from '../../local/local-jobs'
 import { ensureAppPackages } from '../../project-bootstrap'
 import { flagBool, flagString, type Command, type CommandContext } from '../types'
 
@@ -395,10 +396,11 @@ async function check(ctx: CommandContext) {
     }
     if (step === 'start') {
       if (running(project)) {
-        // Running, with keys it can't read: every later step would fail on a secret or an Action record.
-        const state = readState(project)!
-        const keyProblem = await runtimeKeyCustodianProblem(`http://127.0.0.1:${state.ports.service}`)
-        if (keyProblem) record({ step, status: 'failed', note: keyProblem, ms: 0 })
+        // Running, with keys it can't read (every later step would fail on a secret or an Action record),
+        // or with a jobs engine that delivers nothing (every later step that writes waits on it).
+        const service = `http://127.0.0.1:${readState(project)!.ports.service}`
+        const problem = (await runtimeKeyCustodianProblem(service)) ?? (await runtimeJobsProblem(service))
+        if (problem) record({ step, status: 'failed', note: problem, ms: 0 })
         else record({ step, status: 'skipped', note: 'the runtime is already running', ms: 0 })
       } else await command(step, root, self(['local', 'start']), 'frontera local start')
       continue

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

@@ -40,7 +40,7 @@ import { agentFilesProblem, caseConcurrency, caseCount, caseRepeat, DEFAULT_PASS
 import { compareWithRun, comparisonWords, listTestRuns, readTestRun, runOnModel, saveTestRun, stuckWords } from '../../local/local-test-models'
 import { modelSubstitutions, skippedCases, skippedWords } from '../../local/local-test-scope'
 import { devServerLine, listDevServers, stopDevServers } from '../../mcp/mcp-apps'
-import { restartJobs } from '../../local/local-jobs'
+import { JOBS_STALL_FIX, restartJobs, runtimeJobsProblem } from '../../local/local-jobs'
 import { conversationTranscript } from '../../mcp/mcp-conversations'
 import { runtimeLink } from '../../mcp/mcp-runtime'
 import { caseTraces, evidenceLine, failingCaseEvidence } from '../../local/local-case-evidence'
@@ -470,7 +470,11 @@ async function status(ctx: CommandContext) {
   // What the runtime holds with no file in the project (an Agent whose folder was deleted): said with its fix.
   const orphans = (state.phase === 'ready' && isAlive(state.supervisorPid) && state.credentials ? await projectOrphans(project, `http://127.0.0.1:${state.ports.service}`, state.credentials).catch(() => null) : null) ?? []
   // Encryption keys the runtime can't read (data keys a hosted OpenBao locked): every secret and governed Action record fails until a reset.
-  const keyProblem = state.phase === 'ready' && isAlive(state.supervisorPid) ? await runtimeKeyCustodianProblem(`http://127.0.0.1:${state.ports.service}`) : null
+  // And governed work the jobs engine has left waiting: its port can answer while its calls into the service fail, so its line above says running.
+  // Read together: each waits up to 3 s on a service that doesn't answer.
+  const [keyProblem, jobsProblem] = state.phase === 'ready' && isAlive(state.supervisorPid)
+    ? await Promise.all([runtimeKeyCustodianProblem(`http://127.0.0.1:${state.ports.service}`), runtimeJobsProblem(`http://127.0.0.1:${state.ports.service}`)])
+    : [null, null]
   // Who last changed the runtime or the files, one line per session, and the run holding the runtime (X9).
   const writers = recentWriters(project.stateDir)
   const lock = readLock(project.stateDir)
@@ -495,12 +499,14 @@ async function status(ctx: CommandContext) {
       // On the runtime, not in the files: each with what fixes it (`local dev` archives an Agent or workflow whose file was deleted).
       ...(orphans.length ? { notInProject: orphans } : {}),
       ...(keyProblem ? { keyCustodian: { problem: keyProblem, fix: KEY_CUSTODIAN_FIX } } : {}),
+      ...(jobsProblem ? { jobsDelivery: { problem: jobsProblem, fix: JOBS_STALL_FIX } } : {}),
       writers,
       ...(lock ? { lock: { command: lock.command, session: lock.session, harness: lock.harness, since: lock.since } } : {}),
     },
     text: [
       renderStatus({ ...state, components }, project, undefined, live, setIds, personas, secrets, liveApps ?? null, down),
       ...(keyProblem ? ['', 'Encryption keys', `  ✕ ${keyProblem}`] : []),
+      ...(jobsProblem ? ['', 'Jobs', `  ✕ ${jobsProblem}`] : []),
       ...(stuck.length ? ['', 'Knowledge', ...stuck.map((k) => `  warning: ${k.problem}`)] : []),
       ...(orphans.length ? ['', 'On the runtime, not in the project', ...orphans.map((o) => `  warning: ${orphanLine(o)}`)] : []),
       ...(devServers.length ? ['', 'App dev servers', ...devServers.map((s) => `  ${devServerLine(s)}`)] : []),