@frontera-sdk/cli 1.43.9 → 1.44.0

package/src/commands/app/init.ts

@@ -1,30 +1,194 @@
-import { join } from 'node:path'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
 
+import { detectAdoption, mergeManifest, planAdoption } from '../../adopt'
 import { UsageError } from '../../errors'
-import { scaffold, scaffoldFiles } from '../../template'
+import {
+  assertTargetAvailable,
+  initGitRepository,
+  installDependencies,
+  validateAppName,
+} from '../../project-bootstrap'
+import { BASELINE_COMPONENTS, addShadcnComponents, shadcnAddCommand } from '../../shadcn-components'
+import { scaffold, scaffoldFiles, type AppFramework } from '../../template'
 import { writeHarnessFiles } from '../../harness'
 import { DEV_ENV_FILE, writeDevEnv } from '../../dev-env'
-import type { Command } from '../types'
+import { flagBool, flagString, type Command, type CommandContext, type CommandResult } from '../types'
+
+/**
+ * Scaffold a project someone can start working in.
+ *
+ * The bar is the one every other framework's `create-*` command already meets:
+ * refuse a name or a directory that cannot work BEFORE writing anything, say
+ * what is being made and where, install it, put it on a first commit, and end
+ * with commands that are correct for the project that now exists. Stopping at
+ * "files written" left the author to retype four commands and to discover the
+ * failures — an occupied directory, an invalid package name — after the damage.
+ */
+/**
+ * Initialise an existing Next.js project in place.
+ *
+ * Writes what did not exist, adds the keys that were missing, and REPORTS
+ * everything it will not do for you. The three files it refuses to rewrite —
+ * the Next config, the root layout, the stylesheet — are the ones where a
+ * codemod that guesses wrong is indistinguishable from vandalism, and where the
+ * author is the only one who knows what the surrounding code means.
+ *
+ * No `git init` here, ever: an existing project has whatever history it has.
+ */
+async function adoptExistingProject(ctx: CommandContext, root: string): Promise<CommandResult> {
+  const target = detectAdoption(root)
+  const force = flagBool(ctx, 'force')
+  if (target.alreadyAdopted && !force) {
+    throw new UsageError(
+      `${root} is already a Frontera App`,
+      'frontera.config.json is already here — pass --force to rewrite what is missing',
+    )
+  }
+
+  const plan = planAdoption(target)
+  // The same CLI skill `frontera init` writes; it skips files that exist.
+  const harness = writeHarnessFiles(root)
+
+  ctx.output.note(`Initializing a Frontera App in ${root}`)
+  ctx.output.note('')
+  ctx.output.note(`  router      ${target.appDir}/ (App Router)`)
+  ctx.output.note(`  stylesheet  ${target.css}`)
+  ctx.output.note(`  alias       ${target.alias}/`)
+  ctx.output.note('')
+
+  for (const [path, content] of Object.entries(plan.files)) {
+    const full = join(root, path)
+    mkdirSync(dirname(full), { recursive: true })
+    writeFileSync(full, content)
+  }
+  const written = Object.keys(plan.files)
+  ctx.output.note(`  ${written.length} files written, existing files untouched`)
+
+  const manifestPath = join(root, 'package.json')
+  const added = [
+    ...Object.keys(plan.dependencies),
+    ...Object.keys(plan.devDependencies),
+    ...Object.keys(plan.scripts),
+  ]
+  if (added.length > 0) {
+    writeFileSync(manifestPath, mergeManifest(readFileSync(manifestPath, 'utf8'), plan))
+    ctx.output.note(`  package.json  + ${added.join(', ')}`)
+  }
+  ctx.output.note('')
+
+  let installed = false
+  const needsInstall = Object.keys(plan.dependencies).length + Object.keys(plan.devDependencies).length > 0
+  if (needsInstall && !flagBool(ctx, 'no-install')) {
+    ctx.output.note('Installing dependencies with bun…')
+    const result = await installDependencies(root)
+    installed = result.installed
+    ctx.output.note(result.installed ? `  ${result.summary}` : `  install skipped: ${result.summary}`)
+    ctx.output.note('')
+  }
+
+  // The manual steps are the point of the command, not an apology for it: an
+  // adopted project is not finished until they are done, so they are the last
+  // thing on screen and they carry the exact edit.
+  const next = [
+    `  cd ${root}`,
+    ...(installed || !needsInstall ? [] : ['  bun install']),
+    '  frontera app dev',
+    '  bun run build',
+  ]
+
+  return {
+    data: {
+      mode: 'adopted',
+      path: root,
+      appDir: target.appDir,
+      files: written,
+      dependencies: [...Object.keys(plan.dependencies), ...Object.keys(plan.devDependencies)],
+      scripts: Object.keys(plan.scripts),
+      manual: plan.manual,
+      harnessFiles: harness.written,
+      installed,
+    },
+    text: [
+      `Adopted ${target.packageName} at ${root}`,
+      ...(plan.manual.length > 0
+        ? ['', 'Finish by hand — these edit files you already wrote:', ...plan.manual.map((m) => `  · ${m}`)]
+        : []),
+      '',
+      ...next,
+      '',
+      '  AGENTS.md and .agents/skills/ carry the patterns this project now follows.',
+    ].join('\n'),
+  }
+}
 
 export const appInit: Command = {
   meta: {
     noun: 'app',
     verb: 'init',
-    args: [{ name: 'name', required: true, description: 'directory and bootstrap slug for the new app' }],
-    flags: { dir: 'string' },
-    summary: 'Scaffold a new Frontera app project',
-    examples: ['frontera app init shipments-console'],
+    args: [
+      {
+        name: 'name',
+        required: false,
+        description: 'directory to create; omit to adopt the project in the current directory',
+      },
+    ],
+    flags: {
+      dir: 'string',
+      framework: 'string',
+      'no-install': 'boolean',
+      'no-git': 'boolean',
+      'no-components': 'boolean',
+      force: 'boolean',
+    },
+    summary: 'Create a new Frontera App, or adopt the existing project here',
+    examples: [
+      'frontera app init shipments-console',
+      'frontera app init',
+      'frontera app init legacy-console --framework react',
+      'frontera app init shipments-console --no-install --no-git --no-components',
+    ],
     // Scaffolding must work before a credential exists.
     offline: true,
   },
 
   async run(ctx) {
     const name = ctx.positional[0]
-    if (!name) throw new UsageError('missing <name>', 'frontera app init <name>')
+    const base = flagString(ctx, 'dir') ?? ctx.cwd
+
+    /**
+     * Which of the two jobs this is, decided the way `shadcn init` decides it:
+     * a `package.json` at the target means initialise IN PLACE, its absence
+     * means create. An FDE usually meets the second case first — the customer
+     * already has an app, or the work started from `create-next-app` — and
+     * "scaffold a new one and copy your code across" is not an answer.
+     */
+    const adoptTarget = resolve(name ? join(base, name) : base)
+    if (existsSync(join(adoptTarget, 'package.json'))) {
+      return adoptExistingProject(ctx, adoptTarget)
+    }
+    if (!name) {
+      throw new UsageError(
+        `no package.json in ${adoptTarget}`,
+        'run `frontera app init <name>` to create a project, or cd into an existing one',
+      )
+    }
 
-    const base = typeof ctx.flags.dir === 'string' ? ctx.flags.dir : ctx.cwd
-    const target = join(base, name)
-    scaffold(target, name)
+    const requested = flagString(ctx, 'framework')
+    if (requested !== undefined && requested !== 'next' && requested !== 'react') {
+      throw new UsageError('unsupported framework', 'use --framework next or --framework react')
+    }
+    const framework: AppFramework = (requested as AppFramework | undefined) ?? 'next'
+    const target = resolve(join(flagString(ctx, 'dir') ?? ctx.cwd, name))
+
+    // Both checks precede the first write. A scaffold that fails halfway is
+    // worse than one that never started, because the caller cannot tell which
+    // of the files in front of them are theirs.
+    validateAppName(name)
+    assertTargetAvailable(target)
+
+    const files = scaffoldFiles(name, framework)
+    scaffold(target, name, framework)
     // The app project is also a directory a harness will work in, so it gets
     // the same AGENTS.md + CLI skill that `frontera init` writes.
     const harness = writeHarnessFiles(target)
@@ -32,12 +196,27 @@ export const appInit: Command = {
     // The SDK is written into `src/frontera/` rather than declared as a
     // dependency, so `package.json` asks for nothing but public npm and this
     // installs on a laptop or in a sandbox that has never seen the monorepo.
-    // Reported here because it is the one surprising thing about the tree, and
-    // an agent that does not know it will try to "fix" the imports.
-    const vendored = Object.keys(scaffoldFiles(name)).filter((f) =>
-      f.startsWith('src/frontera/'),
-    ).length
-    ctx.output.note(`  SDK vendored into src/frontera/ (${vendored} files) — imports resolve by alias`)
+    // Reported because it is the one surprising thing about the legacy tree,
+    // and an agent that does not know it will try to "fix" the imports.
+    const vendored = Object.keys(files).filter((f) => f.startsWith('src/frontera/')).length
+    const skills = Object.keys(files).filter((f) => f.endsWith('SKILL.md')).length
+
+    ctx.output.note(`Creating a Frontera App in ${target}`)
+    ctx.output.note('')
+    ctx.output.note(
+      `  framework   ${framework === 'next' ? 'Next.js (static export)' : 'Vite + React (legacy)'}`,
+    )
+    ctx.output.note(
+      vendored > 0
+        ? `  SDK         vendored into src/frontera/ (${vendored} files) — imports resolve by alias`
+        : '  SDK         public @frontera-sdk packages, versioned with the App dependencies',
+    )
+    ctx.output.note(
+      framework === 'next'
+        ? `  patterns    ${skills + harness.written.length} skills, and a reference feature under src/ui/`
+        : `  patterns    ${skills + harness.written.length} skills`,
+    )
+    ctx.output.note('')
 
     // The dev host reads VITE_FRONTERA_TOKEN and 401s on every platform read
     // without it. The credential is already on this machine; only a scaffolded
@@ -47,28 +226,91 @@ export const appInit: Command = {
     //
     // Best-effort by construction: `offline: true` above means this command
     // must work before anyone has logged in.
-    const devEnv = writeDevEnv(target)
-    ctx.output.note(
-      devEnv.written
-        ? `  ${DEV_ENV_FILE} written — the dev host will read real data`
-        : `  no ${DEV_ENV_FILE} (${devEnv.reason === 'no-credential' ? 'no stored credential' : devEnv.reason}) — the dev host will mount but platform reads will 401`,
-    )
+    const devEnv = framework === 'react' ? writeDevEnv(target) : { written: false as const, reason: 'not-needed' }
+    if (framework === 'react') {
+      ctx.output.note(
+        devEnv.written
+          ? `  ${DEV_ENV_FILE} written — the dev host will read real data`
+          : `  no ${DEV_ENV_FILE} (${devEnv.reason === 'no-credential' ? 'no stored credential' : devEnv.reason}) — the dev host will mount but platform reads will 401`,
+      )
+      ctx.output.note('')
+    }
+
+    let installed = false
+    if (!flagBool(ctx, 'no-install')) {
+      ctx.output.note('Installing dependencies with bun…')
+      const result = await installDependencies(target)
+      installed = result.installed
+      ctx.output.note(
+        result.installed
+          ? `  ${result.summary}`
+          : `  install skipped: ${result.summary} — run \`bun install\` when you have a network`,
+      )
+      ctx.output.note('')
+    }
+
+    // Shared primitives come from the shadcn registry rather than a library
+    // this repository maintains, so they are fetched rather than written. The
+    // reference feature imports them, which is why a failure has to name the
+    // command that finishes the job instead of being swallowed.
+    let components = false
+    if (framework === 'next' && !flagBool(ctx, 'no-components')) {
+      ctx.output.note(`Adding shadcn components: ${BASELINE_COMPONENTS.join(', ')}…`)
+      const result = await addShadcnComponents(target)
+      components = result.added
+      ctx.output.note(result.added ? `  ${result.summary}` : `  not added: ${result.summary}`)
+      ctx.output.note('')
+    }
+
+    const git = flagBool(ctx, 'no-git')
+      ? { initialized: false, reason: 'skipped' as const }
+      : await initGitRepository(target)
+    if (git.initialized) {
+      ctx.output.note('Initialized a git repository with an initial commit.')
+      ctx.output.note('')
+    } else if (git.reason === 'already-in-repository') {
+      ctx.output.note('Inside an existing git repository — no repository created.')
+      ctx.output.note('')
+    }
+
+    const next = [
+      `  cd ${name}`,
+      ...(installed ? [] : ['  bun install']),
+      // Whenever they are absent — skipped or failed. The reference feature
+      // imports these files, so without them the first `bun run check` fails
+      // on a missing module and the cause is two screens up.
+      ...(framework === 'next' && !components ? [`  ${shadcnAddCommand()}`] : []),
+      // The legacy Vite scaffold has neither `frontera app dev` as its entry
+      // point nor a `check` script; printing commands it does not have is how
+      // a first session starts with an error.
+      ...(framework === 'react'
+        ? ['  bun run dev', '  bun run typecheck', '  bun run build']
+        : ['  frontera app dev', '  bun run check']),
+      '  frontera app deploy --no-promote',
+    ]
 
     return {
       data: {
         name,
+        framework,
         path: target,
+        files: Object.keys(files).length,
+        skills,
         harnessFiles: harness.written,
         vendoredSdkFiles: vendored,
         devEnvWritten: devEnv.written,
+        installed,
+        components,
+        gitInitialized: git.initialized,
       },
       text: [
-        `Scaffolded ${name}`,
+        `Success! Created ${name} at ${target}`,
+        '',
+        ...next,
         '',
-        `  cd ${name}`,
-        '  bun install',
-        '  bun run build',
-        '  frontera app deploy',
+        // The tree carries its own instructions; saying so is what makes an
+        // agent read them instead of inferring a house style from one file.
+        '  AGENTS.md routes to the patterns this project already follows.',
       ].join('\n'),
     }
   },

package/src/commands/app/sdk.ts

@@ -0,0 +1,31 @@
+import { UsageError } from '../../errors'
+import { syncVendoredAppSdk } from '../../sdk-sync'
+import { requireProjectFrom } from './shared'
+import type { Command } from '../types'
+
+export const appSdk: Command = {
+  meta: {
+    noun: 'app',
+    verb: 'sdk',
+    args: [{ name: 'action', required: true, description: 'sync' }],
+    flags: {},
+    summary: 'Refresh the generated SDK tree in a legacy vendored App',
+    examples: ['frontera app sdk sync'],
+    needsProject: true,
+  },
+  async run(ctx) {
+    if (ctx.positional[0] !== 'sync') throw new UsageError('expected sync', 'frontera app sdk sync')
+    const project = requireProjectFrom(ctx)
+    const result = syncVendoredAppSdk(project.root)
+    if (result.kind === 'published') {
+      return {
+        data: result,
+        text: 'This App uses published @frontera-sdk packages; update them with the package manager.',
+      }
+    }
+    return {
+      data: result,
+      text: `Synced vendored Frontera SDK ${result.before} → ${result.after} (${result.fileCount} files).`,
+    }
+  },
+}

package/src/commands/app/versions.ts

@@ -30,7 +30,14 @@ export const appVersions: Command = {
                 (v) =>
                   `${v.deployed ? '*' : ' '} ${v.version.padEnd(12)} ` +
                   `parent=${(v.parentVersion ?? '-').padEnd(10)} ` +
-                  `${v.fileCount} files  ${formatBytes(v.totalBytes)}`,
+                  `${v.fileCount} files  ${formatBytes(v.totalBytes)}  ` +
+                  `${v.runtime}/${v.routing}` +
+                  (v.provenance?.framework
+                    ? `  ${v.provenance.framework}${v.provenance.frameworkVersion ? `@${v.provenance.frameworkVersion}` : ''}`
+                    : '') +
+                  (v.provenance?.sourceCommit
+                    ? `  source=${v.provenance.sourceCommit.slice(0, 8)}${v.provenance.sourceDirty ? '+dirty' : ''}`
+                    : ''),
               )
               .join('\n'),
     }

package/src/commands/blueprint/editable.ts

@@ -0,0 +1,151 @@
+import { BlueprintAuthoringApi } from '../../api/blueprint-authoring-api'
+import { CliError, UsageError } from '../../errors'
+import type { Command, CommandContext } from '../types'
+
+/**
+ * Declare which properties a governed Action may write.
+ *
+ * The `set_editable_properties` draft command has existed since the edit
+ * overlay landed, and until now nothing called it: `apply` excludes backings
+ * from its diff (`bind` owns them) and `bind` sends only the column mapping.
+ * So the one declaration standing between a published ontology and an Action
+ * that can change it was reachable by raw HTTP alone.
+ *
+ * It is its own verb rather than a flag on `bind` because narrowing the set is
+ * a governed act with its own consequence — an edit already stored against a
+ * property that stops being editable is no longer readable — and the service
+ * refuses a rebind while any are set for exactly that reason.
+ */
+
+function nameList(value: string | boolean | undefined): string[] {
+  if (typeof value !== 'string') return []
+  return value.split(',').map((entry) => entry.trim()).filter(Boolean)
+}
+
+/**
+ * The next editable set, as API names.
+ *
+ * Exported for the tests: the selection is where a caller's mistake turns into
+ * the wrong contract, and it is worth pinning without a draft to run against.
+ *
+ * `--set` replaces, `--add`/`--remove` compose against what is already there,
+ * and the result is deduplicated and sorted so restating the same intent in
+ * another order produces the same command — the service sorts the ids for the
+ * same reason, to keep the bundle digest stable.
+ */
+export function nextEditableSelection(
+  current: readonly string[],
+  selection: { set?: string[]; add?: string[]; remove?: string[] },
+): string[] {
+  const base = selection.set ?? [...current]
+  const removed = new Set(selection.remove ?? [])
+  const next = new Set([...base, ...(selection.add ?? [])].filter((name) => !removed.has(name)))
+  return [...next].sort()
+}
+
+function api(ctx: CommandContext): BlueprintAuthoringApi {
+  return new BlueprintAuthoringApi(ctx.apiUrl, ctx.token)
+}
+
+export const blueprintEditable: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'editable',
+    args: [{ name: 'objectType', required: true, description: 'The object type’s API name' }],
+    flags: { set: 'string', add: 'string', remove: 'string' },
+    summary: 'Declare which properties a governed Action may edit',
+    examples: [
+      'frontera blueprint editable SupportTicket',
+      'frontera blueprint editable SupportTicket --set priority,escalated',
+      'frontera blueprint editable SupportTicket --add customerTier',
+      'frontera blueprint editable SupportTicket --set ""',
+    ],
+  },
+
+  async run(ctx) {
+    const apiName = ctx.positional[0]
+    if (!apiName) throw new UsageError('missing <objectType>', 'frontera blueprint editable SupportTicket')
+
+    // `--set ''` is how the set is cleared, and it is a different intent from
+    // passing no flag at all — so presence is what selects the mode, never
+    // whether the parsed list came back empty.
+    const hasSet = typeof ctx.flags.set === 'string'
+    const add = nameList(ctx.flags.add)
+    const remove = nameList(ctx.flags.remove)
+    if (hasSet && (add.length > 0 || remove.length > 0)) {
+      throw new UsageError(
+        '--set replaces the whole set, so it cannot be combined with --add or --remove.',
+        `frontera blueprint editable ${apiName} --set ${[...nameList(ctx.flags.set), ...add].join(',')}`,
+      )
+    }
+
+    const client = api(ctx)
+    const detail = await client.getObjectTypeDetail(apiName)
+    if (!detail?.id) {
+      throw new CliError(`No object type "${apiName}" on the draft.`, {
+        code: 'NOT_FOUND',
+        hint: 'frontera blueprint catalog',
+      })
+    }
+
+    const known = new Set(detail.properties.map((property) => property.apiName).filter(Boolean))
+    // Already API names: the draft stores ids, and the catalog resolves them on
+    // the way out. Mapping them through the property ids again read every one
+    // as unknown and reported an empty set — which would have let `--add` post
+    // a set containing only the addition, silently dropping the rest.
+    const current = [...detail.editableProperties].sort()
+
+    if (!hasSet && add.length === 0 && remove.length === 0) {
+      return {
+        data: { objectType: apiName, editable: current },
+        text: current.length === 0
+          ? `"${apiName}" has no editable properties — no Action can change it yet.`
+          : `"${apiName}" editable: ${current.join(', ')}`,
+      }
+    }
+
+    const next = nextEditableSelection(current, {
+      ...(hasSet ? { set: nameList(ctx.flags.set) } : {}),
+      add,
+      remove,
+    })
+
+    // Refused here rather than at the service, which answers for the first
+    // unknown name it reaches. The properties came from the same read, so this
+    // can name all of them at once and list what the type actually has.
+    const unknown = next.filter((name) => !known.has(name))
+    if (unknown.length > 0) {
+      throw new CliError(
+        `${unknown.join(', ')} ${unknown.length === 1 ? 'is not a property' : 'are not properties'} of "${apiName}".`,
+        {
+          code: 'USAGE',
+          hint: `Properties: ${[...known].sort().join(', ')}`,
+        },
+      )
+    }
+
+    if (next.length === current.length && next.every((name, index) => name === current[index])) {
+      return {
+        data: { objectType: apiName, editable: current, changed: false },
+        text: `"${apiName}" editable is already ${current.length === 0 ? 'empty' : current.join(', ')}.`,
+      }
+    }
+
+    const result = await client.draftCommand({
+      kind: 'set_editable_properties',
+      objectId: detail.id,
+      editableProperties: next,
+    }, await client.revision())
+
+    const dropped = current.filter((name) => !next.includes(name))
+    return {
+      data: { objectType: apiName, editable: next, dropped, revision: result.revision },
+      // Narrowing is called out, because an edit already stored against a
+      // dropped property stops being read — the one consequence of this
+      // command a caller cannot see from the new set alone.
+      text: `"${apiName}" editable: ${next.length === 0 ? '(none)' : next.join(', ')}`
+        + (dropped.length > 0 ? `\nNo longer editable: ${dropped.join(', ')} — edits already stored against them stop being read.` : '')
+        + '\n\nPublish a release for this to reach an Action.',
+    }
+  },
+}

package/src/commands/blueprint/generate-types.ts

@@ -0,0 +1,58 @@
+import { relative } from 'node:path'
+
+import { PlatformApi } from '../../api/platform-api'
+import {
+  generateBlueprintTypes,
+  parseBlueprintSchema,
+  writeBlueprintTypesFile,
+} from '../../blueprint-types'
+import type { Command } from '../types'
+import { flagBool, flagString } from '../types'
+
+export const blueprintGenerateTypes: Command = {
+  meta: {
+    noun: 'blueprint',
+    verb: 'generate-types',
+    args: [],
+    flags: { output: 'string', check: 'boolean' },
+    summary: 'Generate App-local TypeScript types from this workspace Blueprint',
+    examples: [
+      'frontera blueprint generate-types',
+      'frontera blueprint generate-types --check',
+      'frontera blueprint generate-types --output src/contracts/blueprint.ts',
+    ],
+    needsProject: true,
+  },
+
+  async run(ctx) {
+    const project = ctx.project!
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const schema = parseBlueprintSchema(await api.blueprintSchema())
+    const contents = generateBlueprintTypes(schema)
+    const written = writeBlueprintTypesFile(
+      project.root,
+      flagString(ctx, 'output'),
+      contents,
+      flagBool(ctx, 'check'),
+    )
+    const path = relative(project.root, written.path)
+    const propertyCount = schema.objectTypes.reduce((total, objectType) => total + objectType.properties.length, 0)
+    const checked = flagBool(ctx, 'check')
+
+    return {
+      data: {
+        path,
+        digest: schema.digest,
+        objectCount: schema.objectTypes.length,
+        propertyCount,
+        changed: written.changed,
+        checked,
+      },
+      text: checked
+        ? `Blueprint types are current at ${path} (${schema.objectTypes.length} objects, ${propertyCount} properties).`
+        : written.changed
+          ? `Generated Blueprint types at ${path} (${schema.objectTypes.length} objects, ${propertyCount} properties).`
+          : `Blueprint types already current at ${path} (${schema.objectTypes.length} objects, ${propertyCount} properties).`,
+    }
+  },
+}