@frontera-sdk/cli 1.44.1 → 1.45.0

package/src/auth-verify.ts

@@ -0,0 +1,105 @@
+import { PlatformApi } from './api/platform-api'
+import { CliError, UsageError } from './errors'
+import type { CredentialKind } from './profiles'
+
+export interface VerifiedKey {
+  kind: CredentialKind
+  workspaceId: string | null
+  orgId: string | null
+}
+
+/**
+ * Two credential kinds reach this CLI, and they are not interchangeable:
+ *
+ *   sk-ws-   a WORKSPACE key — one workspace's slice of the platform.
+ *   sk-org-  an ORGANIZATION key — the organization-level Blueprint draft,
+ *            which no workspace credential can reach, because that draft is
+ *            shared by every workspace in the organization.
+ *
+ * Both are stored the same way; only the verification differs, because an
+ * organization key belongs to no workspace and `whoami` has none to report.
+ */
+export function classifyKey(token: string): CredentialKind {
+  if (token.startsWith('sk-ws-')) return 'workspace'
+  if (token.startsWith('sk-org-')) return 'organization'
+  throw new UsageError(
+    'that does not look like a Frontera key',
+    'workspace keys start with sk-ws- (Workspace settings → API Keys); '
+    + 'organization keys start with sk-org- (Settings → API keys)',
+  )
+}
+
+/**
+ * Prove the key works BEFORE it is stored.
+ *
+ * Storing an unusable credential only moves the failure to the next command,
+ * where the cause is no longer obvious — and the check costs one request that
+ * also reports which workspace the key just bound to.
+ */
+export async function verifyKey(apiUrl: string, token: string): Promise<VerifiedKey> {
+  const kind = classifyKey(token)
+
+  if (kind === 'workspace') {
+    const me = await new PlatformApi(apiUrl, token).whoami().catch(() => null)
+    if (!me?.workspaceId) {
+      throw new CliError('the token was rejected by this API origin', {
+        code: 'UNAUTHORIZED',
+        hint: `check the key is enabled, and that the origin is right (currently ${apiUrl})`,
+      })
+    }
+    return { kind, workspaceId: me.workspaceId, orgId: me.orgId ?? null }
+  }
+
+  /**
+   * Organization keys verify against an organization-scoped read, because
+   * `/v1/whoami` refuses them: it performs no permission check, and the org-key
+   * lane default-denies any route that neither checks a permission nor declares
+   * itself a read.
+   *
+   * The subtlety is that 200 is NOT the only success. An organization that has
+   * never run `blueprint adopt` has no lifecycle row, so this route answers 404
+   * for a perfectly valid key — requiring 2xx would reject the very keys someone
+   * adds in order to run `adopt`.
+   *
+   * So the question asked is "did a FRONTERA API answer this", not "did it
+   * answer 200". A Frontera error carries the service's envelope
+   * (`{ error: true, code, message }`); a typo'd host's 404 page or a 500 from
+   * something else does not. Without that distinction any non-401 reply counted
+   * as proof, so `auth add --api-url <typo>` sent the key to that host and then
+   * stored it as verified.
+   */
+  const lifecycle = await fetch(`${apiUrl}/v1/blueprint/lifecycle`, {
+    headers: { authorization: `Bearer ${token}` },
+  }).catch(() => null)
+
+  if (!lifecycle) {
+    throw new CliError(`could not reach ${apiUrl}`, {
+      code: 'SERVICE_UNAVAILABLE',
+      hint: 'check the origin and your network, then try again',
+    })
+  }
+  if (lifecycle.status === 401 || lifecycle.status === 403) {
+    throw new CliError('the organization key was rejected by this API origin', {
+      code: 'UNAUTHORIZED',
+      hint: `check the key is active and carries organization:update, and that the origin is right (currently ${apiUrl})`,
+    })
+  }
+  if (!lifecycle.ok && !(await looksLikeFronteraError(lifecycle))) {
+    throw new CliError(`${apiUrl} did not answer like a Frontera API`, {
+      code: 'BAD_REQUEST',
+      hint: `check --api-url for a typo — the key was NOT stored (this origin answered ${lifecycle.status})`,
+    })
+  }
+
+  return { kind, workspaceId: null, orgId: null }
+}
+
+/** The service's error envelope — `{ error: true, code, message }`. */
+async function looksLikeFronteraError(response: Response): Promise<boolean> {
+  try {
+    const body = (await response.json()) as { error?: unknown; code?: unknown }
+    return body?.error === true && typeof body.code === 'string'
+  } catch {
+    return false
+  }
+}

package/src/binding-registry.ts

@@ -0,0 +1,87 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+import { writeFileAtomic } from './fs-atomic'
+import { configDir, type Env } from './paths'
+
+/**
+ * Which directories THIS machine bound to a profile, and to which one.
+ *
+ * `.frontera/context.json` is discovered by walking upward, and the walk cannot
+ * tell who wrote the file it finds. A repository that COMMITS one selects a real
+ * profile — `default` is the name every migrated machine ends up with — and
+ * therefore a real key and a real origin, for every `frontera` command run
+ * inside that checkout. Nothing is printed and nothing is asked.
+ *
+ * The file holds a name rather than a token, which bounds the damage to
+ * deployments the user already has keys for. It does not close the case that
+ * matters: `frontera app pull` in a cloned repository writes a customer's source
+ * into that repository's tree, and the write paths write to the customer's
+ * deployment.
+ *
+ * So selection is answered by the context file and PROVENANCE is answered here.
+ * A binding this machine did not make is not an answer; it is a question, and
+ * `frontera auth use` is how the person answers it.
+ *
+ * Recording a path, not a secret — and only paths the user explicitly bound.
+ */
+
+export interface Binding {
+  profile: string
+  boundAt: string
+}
+
+interface BindingFile {
+  schemaVersion: 1
+  roots: Record<string, Binding>
+}
+
+function bindingsPath(env: Env): string {
+  return join(configDir(env), 'bindings.json')
+}
+
+/** Resolved, so `/tmp` and `/private/tmp` are not two different bindings. */
+function key(root: string): string {
+  return resolve(root)
+}
+
+function read(env: Env): BindingFile {
+  const path = bindingsPath(env)
+  if (!existsSync(path)) return { schemaVersion: 1, roots: {} }
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as BindingFile
+    return { schemaVersion: 1, roots: parsed.roots ?? {} }
+  } catch {
+    // Unlike the credential file, losing this costs no secret and no
+    // configuration — the worst case is that `auth use` must be re-run, which
+    // is the safe direction to fail in.
+    return { schemaVersion: 1, roots: {} }
+  }
+}
+
+export function recordBinding(root: string, profile: string, env: Env = process.env): void {
+  const file = read(env)
+  file.roots[key(root)] = { profile, boundAt: new Date().toISOString() }
+  writeFileAtomic(bindingsPath(env), `${JSON.stringify(file, null, 2)}\n`, 0o600)
+}
+
+export function bindingFor(root: string, env: Env = process.env): Binding | null {
+  return read(env).roots[key(root)] ?? null
+}
+
+export function forgetBinding(root: string, env: Env = process.env): void {
+  const file = read(env)
+  if (!(key(root) in file.roots)) return
+  delete file.roots[key(root)]
+  writeFileAtomic(bindingsPath(env), `${JSON.stringify(file, null, 2)}\n`, 0o600)
+}
+
+/**
+ * Did this machine bind this root to this profile?
+ *
+ * The profile must match too. A committed context that edits the NAME inside a
+ * directory the user did bind is the same attack with an extra step.
+ */
+export function isTrustedBinding(root: string, profile: string, env: Env = process.env): boolean {
+  return bindingFor(root, env)?.profile === profile
+}

package/src/commands/action/deploy.ts

@@ -23,6 +23,7 @@ export const actionDeploy: Command = {
   meta: {
     noun: 'action',
     verb: 'deploy',
+    authLane: 'session',
     args: [{ name: 'action', required: true, description: 'The published Action’s API name' }],
     flags: { 'dry-run': 'boolean', 'plan-id': 'string', 'binding-id': 'string' },
     summary: 'Build and validate the write path for a published Action',

package/src/commands/action/grant.ts

@@ -20,6 +20,7 @@ export const actionGrant: Command = {
   meta: {
     noun: 'action',
     verb: 'grant',
+    authLane: 'session',
     args: [
       { name: 'capability', required: true, description: 'The Action’s invoke capability, as resource:action' },
     ],

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

@@ -2,6 +2,7 @@ import { actionDeploy } from './deploy'
 import { actionGrant } from './grant'
 import { actionList } from './list'
 import { actionPrepare } from './prepare'
+import { actionRequests } from './requests'
 import { actionReview } from './review'
 import type { Command } from '../types'
 
@@ -19,9 +20,16 @@ import type { Command } from '../types'
  * non-member principal — `wskey:…` and `orgkey:…` — and the invoke check joins
  * organization membership, so a `submit` verb here would refuse every call it
  * ever made. It belongs to a credential that represents a person.
+ *
+ * READING those invocations is not the same boundary, and `requests` is here:
+ * the list gates on `actionRequest: ['read']` rather than on membership. The
+ * distinction matters because an armed path that fails every request looks
+ * exactly like one nothing has tried, and until now nothing in the CLI could
+ * tell the two apart.
  */
 export const actionCommands: readonly Command[] = [
   actionList,
+  actionRequests,
   actionPrepare,
   actionDeploy,
   actionReview,

package/src/commands/action/prepare.ts

@@ -17,6 +17,7 @@ export const actionPrepare: Command = {
   meta: {
     noun: 'action',
     verb: 'prepare',
+    authLane: 'session',
     args: [{ name: 'action', required: true, description: 'The drafted Action’s API name' }],
     flags: { reason: 'string' },
     summary: 'Record that a drafted Action ships disabled, so it can be published',

package/src/commands/action/requests.ts

@@ -0,0 +1,111 @@
+import { GovernedActionApi } from '../../api/governed-action-api'
+import { UsageError } from '../../errors'
+import { table } from '../../table'
+import { flagString, type Command } from '../types'
+
+/**
+ * What has actually run through the write path.
+ *
+ * `action list` reports that an Action is published and deployed; `action
+ * review` reports that its Binding is active. Both describe the ARMING, and an
+ * armed path that every caller's request fails against looks identical to one
+ * nothing has tried yet. This is the only verb that can tell them apart.
+ *
+ * Read-only, and that is a boundary rather than an omission: invoking joins
+ * organization membership, which no CLI credential satisfies. Listing gates on
+ * `actionRequest: ['read']`, which a key can hold.
+ */
+export const actionRequests: Command = {
+  meta: {
+    noun: 'action',
+    verb: 'requests',
+    args: [
+      {
+        name: 'requestId',
+        required: false,
+        description: 'one request to open in full; omit to list recent ones',
+      },
+    ],
+    flags: { lifecycle: 'string', limit: 'string', cursor: 'string' },
+    summary: 'List Action requests and how they resolved — or open one',
+    examples: [
+      'frontera action requests',
+      'frontera action requests --lifecycle failed',
+      'frontera action requests <requestId> --json',
+    ],
+  },
+
+  async run(ctx) {
+    const client = new GovernedActionApi(ctx.apiUrl, ctx.token)
+    const requestId = ctx.positional[0]
+
+    if (requestId) {
+      const request = await client.getRequest(requestId)
+      return {
+        data: request,
+        // Flattened rather than curated: the surface records provenance,
+        // attempts and failure detail under names that differ by adapter, and
+        // naming a subset here would hide exactly the field that explains the
+        // failure being investigated.
+        text: table(
+          ['field', 'value'],
+          Object.entries(request).map(([k, v]) => [
+            k,
+            v === null || v === undefined ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v),
+          ]),
+          [undefined, 80],
+        ),
+      }
+    }
+
+    const limitRaw = flagString(ctx, 'limit')
+    const limit = limitRaw === undefined ? undefined : Number(limitRaw)
+    if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > 200)) {
+      throw new UsageError(
+        `--limit must be a whole number between 1 and 200, not "${limitRaw}"`,
+        'try --limit 20',
+      )
+    }
+
+    const page = await client.listRequests({
+      ...(flagString(ctx, 'lifecycle') ? { lifecycle: flagString(ctx, 'lifecycle')! } : {}),
+      ...(limit === undefined ? {} : { limit }),
+      ...(flagString(ctx, 'cursor') ? { cursor: flagString(ctx, 'cursor')! } : {}),
+    })
+
+    if (page.requests.length === 0) {
+      const filtered = flagString(ctx, 'lifecycle')
+      return {
+        data: page,
+        text: filtered
+          ? `No requests with lifecycle "${filtered}".`
+          : 'No Action requests recorded.\n'
+            + '  Nothing has invoked a deployed Action yet — invoking needs a credential\n'
+            + '  that represents a person, so it happens from an agent or the Console.',
+      }
+    }
+
+    return {
+      data: page,
+      text:
+        table(
+          // The request id is here because the detail verb takes it — without
+          // it the listing could not drive `action requests <requestId>`, which
+          // is the only place the failure detail lives. `effectCertainty` is
+          // the column to read on a failure: it separates "the effect landed
+          // and the request still failed" from "nothing happened", which is
+          // the difference between retrying and not.
+          ['created', 'lifecycle', 'effect', 'action', 'request id'],
+          page.requests.map((r) => [
+            r.createdAt ?? '',
+            r.lifecycle ?? '',
+            r.effectCertainty ?? (r.hasEverDispatched ? 'dispatched' : ''),
+            r.actionDefinitionId ?? '?',
+            r.id ?? '',
+          ]),
+          [24, 12, 20, 38, undefined],
+        )
+        + (page.nextCursor ? `\n\nMore requests. Continue with --cursor ${page.nextCursor}` : ''),
+    }
+  },
+}

package/src/commands/action/review.ts

@@ -26,6 +26,7 @@ export const actionReview: Command = {
   meta: {
     noun: 'action',
     verb: 'review',
+    authLane: 'session',
     args: [{ name: 'bindingRevision', required: true, description: 'The Binding revision to review' }],
     flags: { report: 'string', reason: 'string', 'no-activate': 'boolean' },
     summary: 'Review a validated write path and activate it',

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

@@ -3,7 +3,7 @@ import { readFileSync } from 'node:fs'
 import { PlatformApi } from '../../api/platform-api'
 import { CliError, UsageError } from '../../errors'
 import { table } from '../../table'
-import { flagString, type Command, type CommandContext } from '../types'
+import { flagBool, flagString, type Command, type CommandContext } from '../types'
 import { renderComposition, type Lookups } from './compose'
 import { resolveAgentRef, type AgentRow } from './resolve'
 
@@ -86,6 +86,26 @@ async function readDocument(ctx: CommandContext): Promise<Record<string, unknown
   }
 }
 
+/**
+ * JSON with object keys in a fixed order, for comparison.
+ *
+ * `JSON.stringify` preserves insertion order, and the draft snapshot and the
+ * live snapshot are built by different code paths — so the same
+ * `caseDefinition` serialises as `{metrics, objectSets, objectTypes}` on one
+ * side and `{objectTypes, metrics, objectSets}` on the other. Comparing the
+ * strings reported both as changed on a draft that had touched neither, which
+ * is the noise `agent diff` exists to avoid.
+ *
+ * Arrays keep their order: element order is meaningful in `stages` and
+ * `prompts`, where a reordering IS the change.
+ */
+export function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null'
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`
+  const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(',')}}`
+}
+
 /** `agent_configs.agentId` — a slug, lowercase, the value every verb takes. */
 const SLUG_PATTERN = /^[a-z][a-z0-9-]*$/
 
@@ -362,10 +382,39 @@ const diff: Command = {
       'id', 'orgId', 'workspaceId', 'createdAt', 'updatedAt', 'createdBy',
       'currentVersion', 'currentVersionId', 'draft', 'lifecycleStatus',
     ])
-    const changed = Object.keys(draftConfig)
-      .filter((k) => !MANAGED.has(k))
-      .filter((k) => JSON.stringify(draftConfig[k]) !== JSON.stringify(liveConfig[k]))
-      .sort()
+
+    /**
+     * A snapshot is `config` PLUS fifteen sibling sections, and this compared
+     * only `config`.
+     *
+     * So a draft that staged a capability, a skill, a prompt or a knowledge
+     * attachment reported "matches the live version" — the answer a caller
+     * gets when nothing is pending, given immediately after they staged
+     * something. `capability grant` made this reachable in one step, but
+     * `agent apply` has always been able to stage these sections too.
+     *
+     * The live side comes from the live SNAPSHOT rather than the config row:
+     * `GET /config/agents/:id` returns flat scalars with every relation null,
+     * so every section would read as "changed" against it.
+     */
+    const liveSnapshot = await t.api.agentComposition(t.id).catch(() => null)
+    const draftSections = Object.fromEntries(
+      Object.entries(draft.snapshot).filter(([k]) => k !== 'config' && !MANAGED.has(k)),
+    )
+
+    const changed = [
+      ...Object.keys(draftConfig)
+        .filter((k) => !MANAGED.has(k))
+        .filter((k) => stableStringify(draftConfig[k]) !== stableStringify(liveConfig[k])),
+      // Only when the live snapshot could be read. Reporting every section as
+      // changed because one request failed would be worse than the silence
+      // this replaces.
+      ...(liveSnapshot
+        ? Object.keys(draftSections).filter(
+            (k) => stableStringify(draftSections[k]) !== stableStringify(liveSnapshot[k]),
+          )
+        : []),
+    ].sort()
 
     return {
       data: { hasDraft: true, revision: draft.revision, changed },
@@ -410,18 +459,148 @@ const versions: Command = {
       text:
         rows.length === 0
           ? 'No versions published yet.'
+          // The id is here because `agent revert` takes it, and nothing else
+          // prints it — the listing could name a version to go back to and
+          // not the value needed to go there, so the only route was --json.
+          // `publishedByName` before `publishedBy`: the raw column holds a
+          // principal string like `wskey:<uuid>:<uuid>`, which identifies the
+          // credential rather than the person.
           : table(
-              ['version', 'published', 'by'],
+              ['version', 'published', 'by', 'notes', 'id'],
               rows.map((v) => [
                 String(v.versionNumber ?? v.version ?? '?'),
                 String(v.publishedAt ?? ''),
-                String(v.publishedBy ?? ''),
+                String(v.publishedByName ?? v.publishedBy ?? ''),
+                String(v.notes ?? ''),
+                String(v.id ?? ''),
               ]),
+              [7, 26, 22, 24, undefined],
             ),
     }
   },
 }
 
+/**
+ * Bind a workspace skill to an agent.
+ *
+ * The missing step in the skill workflow. `skill push` uploaded a bundle and
+ * nothing loaded it — the only route from a folder to a running agent went
+ * through `pack apply`, which carries a whole pack, or through the Console.
+ *
+ * Unlike `capability grant`, this writes LIVE. There is no draft to publish
+ * and `agent diff` stays empty, because the route binds the skill directly
+ * rather than staging a snapshot patch. Measured, not assumed: attaching one
+ * changes `agent get` immediately and leaves no draft behind. The two verbs
+ * sit next to each other and behave oppositely, so both say which they are.
+ */
+const skillAttach: Command = {
+  meta: {
+    noun: 'agent',
+    verb: 'skill-attach',
+    args: [
+      { name: 'agent', required: true, description: 'agent id or slug' },
+      { name: 'skill', required: true, description: 'workspace skill id, from `frontera skill list`' },
+    ],
+    flags: {},
+    summary: 'Give an agent a workspace skill to load at runtime — takes effect immediately',
+    examples: ['frontera agent skill-attach support-bot <skillId>'],
+  },
+  async run(ctx) {
+    const [ref, skillId] = ctx.positional
+    if (!ref) throw new UsageError('missing <agent>', 'frontera agent list')
+    if (!skillId) throw new UsageError('missing <skill>', 'frontera skill list — then pass an id')
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const result = await api.attachAgentSkill(await resolveAgentRef(api, ref), skillId)
+
+    return {
+      data: result,
+      text: `Attached ${skillId} to ${ref}.\n`
+        + '  Live immediately — this is not staged, and there is nothing to publish.',
+    }
+  },
+}
+
+const skillDetach: Command = {
+  meta: {
+    noun: 'agent',
+    verb: 'skill-detach',
+    args: [
+      { name: 'agent', required: true, description: 'agent id or slug' },
+      { name: 'skill', required: true, description: 'workspace skill id' },
+    ],
+    flags: {},
+    summary: 'Take a workspace skill away from an agent — takes effect immediately',
+    examples: ['frontera agent skill-detach support-bot <skillId>'],
+  },
+  async run(ctx) {
+    const [ref, skillId] = ctx.positional
+    if (!ref) throw new UsageError('missing <agent>', 'frontera agent list')
+    if (!skillId) throw new UsageError('missing <skill>', `frontera agent get ${ref} — lists what it loads`)
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const result = await api.detachAgentSkill(await resolveAgentRef(api, ref), skillId)
+
+    return { data: result, text: `Detached ${skillId} from ${ref}. The skill itself is untouched.` }
+  },
+}
+
+/**
+ * Go back to a version that worked.
+ *
+ * `agent versions` listed what could be reverted to and nothing could revert,
+ * so recovering from a bad publish meant reconstructing the document by hand.
+ *
+ * It RE-POINTS rather than appends: the route applies vN's snapshot to the
+ * live tables and moves `current_version_id` back to vN in one transaction, so
+ * the version list does not grow and the pointer moves backwards. Measured,
+ * not assumed — this was first documented as "publishes a new version", and
+ * reverting a two-version agent left it with two versions, not three. The act
+ * itself is recorded in the agent's event log, which is the append-only trail.
+ *
+ * There is no draft staging: this is live the moment it returns, which is the
+ * opposite of every other write on this noun and the reason it says so in its
+ * own output.
+ */
+const revert: Command = {
+  meta: {
+    noun: 'agent',
+    verb: 'revert',
+    args: [
+      { name: 'agent', required: true, description: 'agent id or slug' },
+      { name: 'version', required: true, description: 'version id to go back to, from `frontera agent versions`' },
+    ],
+    flags: { 'accept-orphaned-knowledge': 'boolean' },
+    summary: 'Restore an earlier version and point the agent back at it',
+    examples: ['frontera agent revert support-bot <versionId>'],
+  },
+  async run(ctx) {
+    const [ref, versionId] = ctx.positional
+    if (!ref) throw new UsageError('missing <agent>', 'frontera agent list')
+    if (!versionId) {
+      throw new UsageError('missing <version>', `frontera agent versions ${ref} — then pass a version id`)
+    }
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const result = await api.revertAgent(await resolveAgentRef(api, ref), versionId, {
+      // The old snapshot can name a knowledge base that has since been
+      // deleted. Refusing by default is right — silently reverting to an agent
+      // that reads a corpus which no longer exists is a working agent with a
+      // missing dependency, which is worse than a refusal.
+      ...(flagBool(ctx, 'accept-orphaned-knowledge') ? { acceptOrphanedKnowledge: true } : {}),
+    })
+
+    return {
+      data: result,
+      text:
+        `${ref} reverted to ${versionId}.\n`
+        + '  Its snapshot is live now and the current-version pointer moved back to it —\n'
+        + '  no new version was created, so `agent versions` is unchanged.\n'
+        + '  This did not stage a draft; there is nothing to publish.',
+    }
+  },
+}
+
 export const agentCommands: Command[] = [
   list,
   get,
@@ -431,4 +610,7 @@ export const agentCommands: Command[] = [
   diff,
   discard,
   versions,
+  revert,
+  skillAttach,
+  skillDetach,
 ]

package/src/commands/app/init.ts

@@ -226,7 +226,7 @@ export const appInit: Command = {
     //
     // Best-effort by construction: `offline: true` above means this command
     // must work before anyone has logged in.
-    const devEnv = framework === 'react' ? writeDevEnv(target) : { written: false as const, reason: 'not-needed' }
+    const devEnv = framework === 'react' ? await writeDevEnv(target) : { written: false as const, reason: 'not-needed' }
     if (framework === 'react') {
       ctx.output.note(
         devEnv.written

package/src/commands/app/pull.ts

@@ -108,7 +108,7 @@ export const appPull: Command = {
     // carries the publisher's — every working copy has to be given one here.
     // Never overwrites, so an author who pointed this project somewhere else
     // keeps their setting.
-    const devEnv = writeDevEnv(dir)
+    const devEnv = await writeDevEnv(dir)
     if (devEnv.written) ctx.output.note(`  ${DEV_ENV_FILE} written — the dev host will read real data`)
 
     const pulled = `Pulled ${count} files from ${app.slug}${parentVersion ? `@${parentVersion}` : ' (draft)'}`