@nifrajs/cli 3.5.0 → 4.0.0

package/src/command-catalog.ts

@@ -13,16 +13,23 @@ import type {
   CapabilityExplainCommandResult,
   CapabilitySnapshotCommandResult,
 } from "./capabilities-tool.ts"
+import { cdnCheckSpec } from "./cdn-check.ts"
 import { type CheckResult, renderCheckReport } from "./check.ts"
 import type { ContractsLock } from "./contracts.ts"
+import { dbAuditSpec, dbQuerySpec, dbRoleSpec, dbSchemaSpec } from "./db-tool.ts"
+import { errorsSpec, logsSpec } from "./dev-feed-tool.ts"
 import { type Diagnostic, diagnostic, normalizeSeverity, toSarifLog } from "./diagnostics.ts"
 import type { DoctorResult } from "./doctor.ts"
+import { type I18nCheckOutput, i18nCheckPassed, renderI18nCheck } from "./i18n-check.ts"
 import type { VerificationLevelsResult } from "./levels-tool.ts"
 import type { LoadedApp } from "./load.ts"
 import type { ManifestEmitCommandResult } from "./manifest-tool.ts"
+import type { LayoutMigrationResult } from "./migrate-layout.ts"
 import { collectPortResult, type PortResult, renderReport } from "./port.ts"
 import type { ReplayResult } from "./replay.ts"
 import { reviewSpec } from "./review.ts"
+import type { RouteTypesReport } from "./route-types.ts"
+import type { SmokeReport } from "./smoke.ts"
 import type { StylexMigrationResult } from "./stylex-migrate.ts"
 import {
   collectProjectWorkGraph,
@@ -79,6 +86,11 @@ export interface CommandSpec<Input, Output> {
   readonly transports: readonly CommandTransport[]
   readonly stability: CommandStability
   readonly argv?: CommandArgvBinding<Input>
+  /**
+   * Input fields only the CLI may set: MCP neither advertises nor accepts them. For a field that acts
+   * with the operator's own credentials, such as a signing key, which an agent must not invoke.
+   */
+  readonly cliOnlyFields?: readonly string[]
   readonly run: (input: Input, ctx: CommandCtx) => Promise<Output>
   readonly render: (out: Output, input?: Input) => readonly string[]
   readonly success?: (out: Output, input: Input) => boolean
@@ -95,6 +107,8 @@ export interface CommandCatalogEntry {
   readonly outputVersion: number
   readonly transports: readonly CommandTransport[]
   readonly stability: CommandStability
+  /** {@link CommandSpec.cliOnlyFields}: present in `inputSchema`, absent from the MCP tool's. */
+  readonly cliOnlyFields: readonly string[]
 }
 
 function freezeJson<T>(value: T): T {
@@ -116,6 +130,20 @@ export function toCommandCatalogEntry<Input, Output>(
     outputVersion: spec.output.version,
     transports: Object.freeze([...spec.transports]),
     stability: spec.stability,
+    cliOnlyFields: Object.freeze([...(spec.cliOnlyFields ?? [])]),
+  })
+}
+
+/** The input schema a command's MCP tool advertises: its catalog schema without CLI-only fields. */
+export function commandMcpInputSchema(entry: CommandCatalogEntry): CommandJsonSchema {
+  const properties = entry.inputSchema.properties
+  if (entry.cliOnlyFields.length === 0 || typeof properties !== "object" || properties === null)
+    return entry.inputSchema
+  return freezeJson({
+    ...entry.inputSchema,
+    properties: Object.fromEntries(
+      Object.entries(properties).filter(([key]) => !entry.cliOnlyFields.includes(key)),
+    ),
   })
 }
 
@@ -324,14 +352,38 @@ interface FixInput {
   readonly dir?: string | undefined
 }
 
+/** `migrate layout`, or `migrate --from tailwind --to stylex`; the parser admits only those two. */
 interface MigrateInput {
-  readonly from: "tailwind"
-  readonly to: "stylex"
+  readonly kind?: "layout" | undefined
+  readonly from?: "tailwind" | undefined
+  readonly to?: "stylex" | undefined
   readonly write?: boolean | undefined
   readonly json?: boolean | undefined
   readonly dir?: string | undefined
 }
 
+interface TargetInput {
+  readonly target?: string | undefined
+  readonly json?: boolean | undefined
+  readonly dir?: string | undefined
+}
+
+interface TargetOutput {
+  readonly ok: boolean
+  readonly target: string
+  /** The target before this run, when it switched one; `undefined` when none was declared. */
+  readonly previous?: string | undefined
+  readonly changed: boolean
+  /** What `nifra build` now emits, and how it deploys. */
+  readonly run: string
+}
+
+interface TypesInput {
+  readonly check?: boolean | undefined
+  readonly json?: boolean | undefined
+  readonly dir?: string | undefined
+}
+
 interface SnapshotInput {
   readonly out?: string | undefined
   readonly json?: boolean | undefined
@@ -376,6 +428,21 @@ interface PortInput {
   readonly dir?: string | undefined
 }
 
+interface SmokeInput {
+  readonly fixture?: string | undefined
+  readonly inProcess?: boolean | undefined
+  readonly json?: boolean | undefined
+  readonly dir?: string | undefined
+}
+
+interface I18nInput {
+  readonly action: "check"
+  readonly entry?: string | undefined
+  readonly json?: boolean | undefined
+  readonly strict?: boolean | undefined
+  readonly dir?: string | undefined
+}
+
 interface CheckCommandOutput extends CheckResult {}
 interface AssureCommandOutput {
   readonly report?: unknown
@@ -406,7 +473,9 @@ interface FixCommandOutput {
   readonly failed: readonly { readonly code: string; readonly reason: string }[]
   readonly diagnostics: readonly unknown[]
 }
-interface MigrateCommandOutput extends StylexMigrationResult {}
+type MigrateCommandOutput =
+  | (StylexMigrationResult & { readonly kind?: undefined })
+  | (LayoutMigrationResult & { readonly kind: "layout" })
 interface SnapshotCommandOutput {
   readonly ok: true
   readonly file: string
@@ -430,6 +499,8 @@ interface SyncCommandOutput {
   readonly results: readonly unknown[]
 }
 
+interface SmokeCommandOutput extends SmokeReport {}
+
 const CHECK_SCHEMA = input<CheckInput>(
   objectSchema({
     lintsOnly: { type: "boolean" },
@@ -648,26 +719,53 @@ const FIX_SCHEMA = input<FixInput>(
 )
 
 const MIGRATE_SCHEMA = input<MigrateInput>(
-  objectSchema(
-    {
-      from: { type: "string", enum: ["tailwind"] },
-      to: { type: "string", enum: ["stylex"] },
-      write: { type: "boolean" },
-      json: { type: "boolean" },
-      dir: { type: "string" },
-    },
-    ["from", "to"],
-  ),
+  objectSchema({
+    kind: { type: "string", enum: ["layout"] },
+    from: { type: "string", enum: ["tailwind"] },
+    to: { type: "string", enum: ["stylex"] },
+    write: { type: "boolean" },
+    json: { type: "boolean" },
+    dir: { type: "string" },
+  }),
   (value) => {
     const raw = withDir(record(value))
+    const flags = {
+      ...parseBooleanFlags(raw, ["write", "json"]),
+      ...(raw.dir === undefined ? {} : { dir: raw.dir }),
+    }
+    const kind = optionalString(raw.kind, "kind")
+    if (kind !== undefined) {
+      if (kind !== "layout")
+        throw new TypeError("the migration must be `layout` (or --from tailwind --to stylex)")
+      return { kind, ...flags }
+    }
     const from = optionalString(raw.from, "from")
     const to = optionalString(raw.to, "to")
     if (from !== "tailwind") throw new TypeError("from must be tailwind")
     if (to !== "stylex") throw new TypeError("to must be stylex")
+    return { from, to, ...flags }
+  },
+)
+
+const TARGET_SCHEMA = input<TargetInput>(
+  objectSchema({ target: { type: "string" }, json: { type: "boolean" }, dir: { type: "string" } }),
+  (value) => {
+    const raw = withDir(record(value))
+    const target = optionalString(raw.target, "target")
     return {
-      from,
-      to,
-      ...parseBooleanFlags(raw, ["write", "json"]),
+      ...parseBooleanFlags(raw, ["json"]),
+      ...(raw.dir === undefined ? {} : { dir: raw.dir }),
+      ...(target === undefined ? {} : { target }),
+    }
+  },
+)
+
+const TYPES_SCHEMA = input<TypesInput>(
+  objectSchema({ check: { type: "boolean" }, json: { type: "boolean" }, dir: { type: "string" } }),
+  (value) => {
+    const raw = withDir(record(value))
+    return {
+      ...parseBooleanFlags(raw, ["check", "json"]),
       ...(raw.dir === undefined ? {} : { dir: raw.dir }),
     }
   },
@@ -790,6 +888,52 @@ const PORT_SCHEMA = input<PortInput>(
   },
 )
 
+const SMOKE_SCHEMA = input<SmokeInput>(
+  objectSchema({
+    fixture: { type: "string" },
+    inProcess: { type: "boolean" },
+    json: { type: "boolean" },
+    dir: { type: "string" },
+  }),
+  (value) => {
+    const raw = withDir(record(value))
+    return {
+      fixture: optionalString(raw.fixture, "fixture"),
+      ...parseBooleanFlags(raw, ["inProcess", "json"]),
+      ...(raw.dir === undefined ? {} : { dir: raw.dir }),
+    }
+  },
+)
+
+const I18N_SCHEMA = input<I18nInput>(
+  objectSchema(
+    {
+      action: { type: "string", enum: ["check"] },
+      entry: { type: "string" },
+      json: { type: "boolean" },
+      strict: { type: "boolean" },
+      dir: { type: "string" },
+    },
+    ["action"],
+  ),
+  (value) => {
+    const raw = withDir(record(value))
+    if (raw.action !== "check") {
+      throw new TypeError(
+        raw.action === undefined
+          ? "i18n needs an action: nifra i18n check [entry]"
+          : `unknown i18n action: ${String(raw.action)} (the one action is check)`,
+      )
+    }
+    return {
+      action: "check",
+      entry: optionalString(raw.entry, "entry"),
+      ...parseBooleanFlags(raw, ["json", "strict"]),
+      ...(raw.dir === undefined ? {} : { dir: raw.dir }),
+    }
+  },
+)
+
 function loadAppFor(ctx: CommandCtx): Promise<LoadedApp> {
   if (ctx.loadApp !== undefined) return ctx.loadApp()
   return import("./load.ts").then(({ loadApp }) => loadApp(ctx.cwd))
@@ -995,6 +1139,8 @@ const manifestSpec: CommandSpec<ManifestInput, ManifestEmitCommandResult | DiffC
   output: output({ type: "object" }),
   transports: ["cli", "mcp"],
   stability: "stable",
+  // The signer is the operator's KMS/HSM callback; an agent signing its own manifest defeats it.
+  cliOnlyFields: ["sign"],
   argv: {
     positionals: ["action", "before", "after"],
     flags: [
@@ -1136,7 +1282,10 @@ const openApiSpec: CommandSpec<OpenApiInput, OpenApiCommandOutput> = {
     ],
   },
   async run(value, ctx) {
-    const app = await loadAppFor(ctx)
+    const app =
+      ctx.loadApp !== undefined
+        ? await ctx.loadApp()
+        : await import("./load.ts").then(({ loadBackendApp }) => loadBackendApp(ctx.cwd))
     const { renderOpenApiWithTypes } = await import("./openapi-tool.ts")
     const format = value.format ?? "json"
     return {
@@ -1252,12 +1401,14 @@ const fixSpec: CommandSpec<FixInput, FixCommandOutput> = {
 
 const migrateSpec: CommandSpec<MigrateInput, MigrateCommandOutput> = {
   name: "migrate",
-  summary: "Migrate safe static Tailwind className utilities to native StyleX props.",
+  summary:
+    "Move an app onto the frontend/backend split (`migrate layout`), or migrate static Tailwind utilities to StyleX.",
   input: MIGRATE_SCHEMA,
   output: output({
     type: "object",
     properties: {
       ok: { type: "boolean" },
+      kind: { type: "string" },
       from: { type: "string" },
       to: { type: "string" },
       write: { type: "boolean" },
@@ -1266,12 +1417,16 @@ const migrateSpec: CommandSpec<MigrateInput, MigrateCommandOutput> = {
       written: { type: "array" },
       issues: { type: "array" },
       files: { type: "array" },
+      splits: { type: "array" },
+      moves: { type: "array" },
+      rewritten: { type: "array" },
     },
-    required: ["ok", "from", "to", "write", "scanned", "changed", "written", "issues", "files"],
+    required: ["ok", "write", "issues"],
   }),
   transports: ["cli"],
   stability: "stable",
   argv: {
+    positionals: ["kind"],
     flags: [
       { name: "from", field: "from", type: "string" },
       { name: "to", field: "to", type: "string" },
@@ -1281,27 +1436,142 @@ const migrateSpec: CommandSpec<MigrateInput, MigrateCommandOutput> = {
     ],
   },
   async run(value, ctx) {
+    const dir = resolve(ctx.cwd, value.dir ?? ".")
+    const write = value.write === undefined ? {} : { write: value.write }
+    if (value.kind === "layout") {
+      const { migrateLayout } = await import("./migrate-layout.ts")
+      return { kind: "layout" as const, ...(await migrateLayout(dir, write)) }
+    }
     const { migrateTailwindToStylex } = await import("./stylex-migrate.ts")
-    return migrateTailwindToStylex(resolve(ctx.cwd, value.dir ?? "."), {
-      ...(value.write === undefined ? {} : { write: value.write }),
-    })
+    return migrateTailwindToStylex(dir, write)
   },
-  render: (out) => [
-    out.ok
-      ? `✓ migrated ${out.changed.length} file${out.changed.length === 1 ? "" : "s"}`
-      : `⚠ migrated ${out.changed.length} safe file${out.changed.length === 1 ? "" : "s"}; ${out.issues.length} manual issue${out.issues.length === 1 ? "" : "s"} remain`,
-    `  scanned ${out.scanned} source file${out.scanned === 1 ? "" : "s"}`,
-    ...(out.write
-      ? [`  wrote ${out.written.length} file${out.written.length === 1 ? "" : "s"}`]
-      : out.changed.length > 0
-        ? ["  dry run: pass --write to apply the safe changes"]
+  render: (out) => {
+    if (out.kind === "layout") {
+      return [
+        out.ok
+          ? `✓ ${out.splits.length} route file${out.splits.length === 1 ? "" : "s"} split, ${out.moves.length} file${out.moves.length === 1 ? "" : "s"} moved`
+          : `⚠ ${out.issues.length} issue${out.issues.length === 1 ? "" : "s"} need a decision; everything else is planned`,
+        ...out.splits.map(
+          (split) => `  split ${split.file} → ${split.backend} (${split.moved.join(", ")})`,
+        ),
+        ...out.moves.map((move) => `  move  ${move.from} → ${move.to}`),
+        ...out.rewritten.map((file) => `  edit  ${file} (imports)`),
+        ...out.issues.map((issue) => `  ⚠ ${issue.file}: ${issue.reason}`),
+        ...(out.write ? [] : ["  dry run: pass --write to apply"]),
+      ]
+    }
+    return [
+      out.ok
+        ? `✓ migrated ${out.changed.length} file${out.changed.length === 1 ? "" : "s"}`
+        : `⚠ migrated ${out.changed.length} safe file${out.changed.length === 1 ? "" : "s"}; ${out.issues.length} manual issue${out.issues.length === 1 ? "" : "s"} remain`,
+      `  scanned ${out.scanned} source file${out.scanned === 1 ? "" : "s"}`,
+      ...(out.write
+        ? [`  wrote ${out.written.length} file${out.written.length === 1 ? "" : "s"}`]
+        : out.changed.length > 0
+          ? ["  dry run: pass --write to apply the safe changes"]
+          : []),
+      ...out.issues
+        .slice(0, 30)
+        .map((issue) => `  ${issue.file}:${issue.line} ${issue.token} — ${issue.reason}`),
+      ...(out.issues.length > 30
+        ? [`  … ${out.issues.length - 30} more issue${out.issues.length - 30 === 1 ? "" : "s"}`]
         : []),
-    ...out.issues
-      .slice(0, 30)
-      .map((issue) => `  ${issue.file}:${issue.line} ${issue.token} — ${issue.reason}`),
-    ...(out.issues.length > 30
-      ? [`  … ${out.issues.length - 30} more issue${out.issues.length - 30 === 1 ? "" : "s"}`]
-      : []),
+    ]
+  },
+  success: (out) => out.ok,
+}
+
+const targetSpec: CommandSpec<TargetInput, TargetOutput> = {
+  name: "target",
+  summary:
+    "Show the app's deploy target, or switch it (`nifra target cloudflare`): the `target` `nifra build` emits, kept in nifra.config.ts.",
+  input: TARGET_SCHEMA,
+  output: output({
+    type: "object",
+    properties: {
+      ok: { type: "boolean" },
+      target: { type: "string" },
+      previous: { type: "string" },
+      changed: { type: "boolean" },
+      run: { type: "string" },
+    },
+    required: ["ok", "target", "changed", "run"],
+  }),
+  transports: ["cli"],
+  stability: "stable",
+  argv: {
+    positionals: ["target"],
+    flags: [
+      { name: "json", field: "json", type: "boolean" },
+      { name: "dir", field: "dir", type: "string" },
+    ],
+  },
+  async run(value, ctx) {
+    const dir = resolve(ctx.cwd, value.dir ?? ".")
+    const { parseBuildTarget, planBuildTarget } = await import("@nifrajs/web/build")
+    const { readConfigTarget, writeConfigTarget } = await import("./config-target.ts")
+    const current = readConfigTarget(dir)
+    const target = parseBuildTarget(
+      value.target ?? current ?? "bun",
+      value.target === undefined ? "target in nifra.config.ts" : "target",
+    )
+    const changed = value.target !== undefined && value.target !== current
+    if (changed) writeConfigTarget(dir, target)
+    return {
+      ok: true,
+      target,
+      ...(changed && current !== undefined ? { previous: current } : {}),
+      changed,
+      run: planBuildTarget(target, "dist").run,
+    }
+  },
+  render: (out) => [
+    out.changed
+      ? `✓ target: ${out.target}${out.previous === undefined ? "" : ` (was ${out.previous})`}`
+      : `target: ${out.target}`,
+    `  nifra build → ${out.run}`,
+  ],
+  success: (out) => out.ok,
+}
+
+const typesSpec: CommandSpec<TypesInput, RouteTypesReport> = {
+  name: "types",
+  summary:
+    "Generate each route's `./+types` module (params, schema-typed data, typed `api`); `--check` fails when one is stale.",
+  input: TYPES_SCHEMA,
+  output: output({
+    type: "object",
+    properties: {
+      ok: { type: "boolean" },
+      check: { type: "boolean" },
+      written: { type: "array" },
+      removed: { type: "array" },
+      stale: { type: "array" },
+      tsconfig: { type: "string" },
+    },
+    required: ["ok", "check", "written", "removed", "stale"],
+  }),
+  transports: ["cli"],
+  stability: "stable",
+  argv: {
+    flags: [
+      { name: "check", field: "check", type: "boolean" },
+      { name: "json", field: "json", type: "boolean" },
+      { name: "dir", field: "dir", type: "string" },
+    ],
+  },
+  async run(value, ctx) {
+    const { routeTypes } = await import("./route-types.ts")
+    return routeTypes(resolve(ctx.cwd, value.dir ?? "."), { check: value.check === true })
+  },
+  render: (out) => [
+    out.check
+      ? out.ok
+        ? "✓ route types are up to date"
+        : `✖ ${out.stale.length} route type file${out.stale.length === 1 ? " is" : "s are"} stale - run \`nifra types\``
+      : `✓ route types: ${out.written.length} written, ${out.removed.length} removed`,
+    ...out.stale.map((file) => `  stale ${file}`),
+    ...(out.tsconfig === undefined ? [] : [`  ⚠ ${out.tsconfig}`]),
   ],
   success: (out) => out.ok,
 }
@@ -1493,6 +1763,34 @@ const replaySpec: CommandSpec<ReplayInput, ReplayResult> = {
   success: (out) => out.ok,
 }
 
+const smokeSpec: CommandSpec<SmokeInput, SmokeCommandOutput> = {
+  name: "smoke",
+  summary:
+    "Run the declared production SSR, mounted-API, 404, header, auth, contract, and hydration smoke checks.",
+  input: SMOKE_SCHEMA,
+  output: output({ type: "object" }),
+  transports: ["cli", "mcp"],
+  stability: "stable",
+  argv: {
+    flags: [
+      { name: "fixture", field: "fixture", type: "string" },
+      { name: "in-process", field: "inProcess", type: "boolean" },
+      { name: "json", field: "json", type: "boolean" },
+    ],
+  },
+  async run(value, ctx) {
+    const { loadSmokeFixture, runSmoke } = await import("./smoke.ts")
+    const fixture = await loadSmokeFixture(ctx.cwd, value.fixture)
+    return runSmoke(fixture, { inProcess: value.inProcess === true })
+  },
+  render: (out) =>
+    out.checks.map(
+      (check) =>
+        `${check.status === "pass" ? "✓" : check.status === "skip" ? "•" : "✖"} ${check.id}${check.message === undefined ? "" : ` - ${check.message}`}`,
+    ),
+  success: (out) => out.ok,
+}
+
 const portSpec: CommandSpec<PortInput, PortResult> = {
   name: "port",
   summary:
@@ -1522,7 +1820,7 @@ const portSpec: CommandSpec<PortInput, PortResult> = {
       return [
         report,
         "",
-        "[nifra] --ci needs a deploy target to gate against, and none was detected. Pass --target <bun|node|deno|cf-pages|vercel>.",
+        "[nifra] --ci needs a deploy target to gate against, and none was detected. Pass --target <bun|node|deno|cloudflare|vercel>.",
       ]
     return [report]
   },
@@ -1535,6 +1833,33 @@ const portSpec: CommandSpec<PortInput, PortResult> = {
   json: (out) => out.json,
 }
 
+// CLI only: it imports app code (the catalogs), which a long-lived MCP server process would cache.
+const i18nSpec: CommandSpec<I18nInput, I18nCheckOutput> = {
+  name: "i18n",
+  summary:
+    "Check i18n catalogs (imports the module exporting `locales` and `catalogs`): coverage, missing and unused keys, ICU syntax, placeholder and tag parity, plural cases, script purity, untranslated messages.",
+  input: I18N_SCHEMA,
+  output: output({ type: "object" }),
+  transports: ["cli"],
+  stability: "stable",
+  argv: {
+    positionals: ["action", "entry"],
+    flags: [
+      { name: "json", field: "json", type: "boolean" },
+      { name: "strict", field: "strict", type: "boolean" },
+    ],
+  },
+  async run(value, ctx) {
+    const { runI18nCheck } = await import("./i18n-check.ts")
+    return runI18nCheck(value.dir === undefined ? ctx.cwd : resolve(ctx.cwd, value.dir), {
+      entry: value.entry,
+    })
+  },
+  render: (out) => renderI18nCheck(out),
+  success: (out, input) => i18nCheckPassed(out, input.strict === true),
+  json: (out) => out,
+}
+
 export const commandSpecs = Object.freeze([
   checkSpec,
   reviewSpec,
@@ -1548,6 +1873,8 @@ export const commandSpecs = Object.freeze([
   doctorSpec,
   fixSpec,
   migrateSpec,
+  targetSpec,
+  typesSpec,
   snapshotSpec,
   diffSpec,
   contractsSpec,
@@ -1555,7 +1882,16 @@ export const commandSpecs = Object.freeze([
   syncRoutesSpec,
   proveSpec,
   replaySpec,
+  smokeSpec,
   portSpec,
+  i18nSpec,
+  errorsSpec,
+  logsSpec,
+  cdnCheckSpec,
+  dbSchemaSpec,
+  dbQuerySpec,
+  dbRoleSpec,
+  dbAuditSpec,
 ] as const)
 
 const commandByName = new Map(commandSpecs.map((spec) => [spec.name, spec]))

package/src/config-target.ts

@@ -0,0 +1,47 @@
+/**
+ * The app's deploy target as `nifra.config.ts` declares it (`export const target = "bun"`), read and
+ * rewritten as text: `nifra port` and `nifra doctor` never run app code, and `nifra target <t>` edits
+ * one line of a file the developer owns.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { CONFIG_FILE } from "./app-files.ts"
+import { stripComments } from "./check-scan.ts"
+
+const TARGET_EXPORT = /\bexport\s+const\s+target\b[^=\n]*=\s*(["'])([^"'\n]*)\1/
+
+/** The `target` string `nifra.config.ts` exports, or `undefined` when it exports none. */
+export function readConfigTarget(appRoot: string): string | undefined {
+  const path = join(appRoot, CONFIG_FILE)
+  if (!existsSync(path)) return undefined
+  return TARGET_EXPORT.exec(stripComments(readFileSync(path, "utf8")))?.[2]
+}
+
+/**
+ * Point `nifra.config.ts` at `target`: rewrite its `target` export, or append one. Returns the previous
+ * value. Throws when the app has no `nifra.config.ts`.
+ */
+export function writeConfigTarget(appRoot: string, target: string): string | undefined {
+  const path = join(appRoot, CONFIG_FILE)
+  if (!existsSync(path)) {
+    throw new Error(
+      `[nifra] no ${CONFIG_FILE} in ${appRoot} - \`nifra target\` sets its \`target\``,
+    )
+  }
+  const text = readFileSync(path, "utf8")
+  // Matched on the comment-blanked text, whose offsets are the original's, so a commented-out
+  // `target` line is never the one rewritten.
+  const found = TARGET_EXPORT.exec(stripComments(text))
+  const previous = found?.[2]
+  let next: string
+  if (found === null) {
+    next = `${text.replace(/\n*$/, "\n")}\n// The deploy target \`nifra build\` emits; \`nifra target <t>\` switches it.\nexport const target = "${target}"\n`
+  } else {
+    // Only the quoted value changes, so a type annotation on the export survives.
+    const end = found.index + found[0].length
+    const start = end - (previous ?? "").length - 2
+    next = `${text.slice(0, start)}"${target}"${text.slice(end)}`
+  }
+  writeFileSync(path, next)
+  return previous
+}