@frontera-sdk/cli 0.1.0 → 1.43.5

package/src/commands/app/deploy.ts

@@ -7,6 +7,7 @@ import { resolveManifest } from '../../manifest'
 import { collectSourceFiles, formatBytes } from '../../packaging'
 import { packDirectory } from '../../pack'
 import { readPackageVersion, writeAppId, writeState } from '../../project'
+import { describeRenderEvidence, readRenderEvidence } from '../../render-evidence'
 import { createTarGz } from '../../tar'
 import { requireProjectFrom } from './shared'
 import { flagBool, flagString, type Command } from '../types'
@@ -23,7 +24,7 @@ async function publish(
   client: AppsApi,
   appId: string,
   args: Parameters<AppsApi['publish']>[1],
-): Promise<{ version: string; promoted: boolean }> {
+): Promise<Awaited<ReturnType<AppsApi['publish']>>> {
   try {
     return await client.publish(appId, args)
   } catch (err) {
@@ -77,6 +78,14 @@ export const appDeploy: Command = {
     const reach = [...manifest.connectDomains, ...manifest.resourceDomains]
     if (reach.length > 0) ctx.output.note(`  may reach ${reach.join(', ')}`)
 
+    // Asked BEFORE the upload, so the answer is about the tree that is being
+    // packaged rather than about whatever the disk looks like afterwards.
+    // Reported whichever way it comes out: "rendered" is worth saying too, and
+    // a line that only ever appears when something is wrong is a line people
+    // learn to skim past.
+    const renderEvidence = readRenderEvidence(project.root)
+    ctx.output.note(describeRenderEvidence(renderEvidence))
+
     const promote = !flagBool(ctx, 'no-promote')
     const res = await publish(client, app.id, {
       version,
@@ -85,6 +94,7 @@ export const appDeploy: Command = {
       source,
       manifest,
       promote,
+      renderEvidence,
     })
 
     writeState(project.root, { appId: app.id, parentVersion: res.version })
@@ -92,14 +102,44 @@ export const appDeploy: Command = {
     // the slug is renamed — and any stale slug is dropped.
     writeAppId(project.root, app.id)
 
+    // The one line that turns "published" into something a person can act on.
+    // A version that was published and not promoted used to be described to
+    // users as one nobody could see — so the turn ended by asking to make an
+    // unreviewed build live for the whole workspace, rather than showing it to
+    // the person who asked for it. It was always viewable; only the URL was
+    // missing.
+    if (res.previewUrl) {
+      ctx.output.note(
+        res.promoted
+          ? `  live at ${res.liveUrl ?? ''} · this exact build: ${res.previewUrl}`
+          : `  open it: ${res.previewUrl}`,
+      )
+    }
+
     return {
-      data: { app: app.slug, appId: app.id, version: res.version, promoted: res.promoted },
+      data: {
+        app: app.slug,
+        appId: app.id,
+        version: res.version,
+        promoted: res.promoted,
+        ...(res.previewUrl ? { previewUrl: res.previewUrl } : {}),
+        ...(res.liveUrl && res.promoted ? { liveUrl: res.liveUrl } : {}),
+        // In `data` as well as in the note: an agent reads the JSON, and this
+        // is the fact it most needs to carry into what it tells the user.
+        rendered: renderEvidence.rendered,
+        renderEvidence,
+      },
       // The slug as the PLATFORM knows it: `project.slug` is a bootstrap name
       // and goes stale the moment the app is renamed, so printing it would
       // report a deploy to an app that no longer exists.
       text:
         `Published ${app.slug}@${res.version}` +
-        (res.promoted ? ' and promoted it' : ' (not promoted — use `frontera app promote`)'),
+        (res.promoted ? ' and promoted it' : '') +
+        (renderEvidence.rendered ? '' : ' — nobody has looked at this version') +
+        // Not "use `frontera app promote`". That read as "invisible until you
+        // promote", which is false and is what sent an agent asking to publish
+        // an unreviewed build to everyone.
+        (res.previewUrl ? `\n\nOpen it: ${res.previewUrl}` : ''),
     }
   },
 }

package/src/commands/app/init.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path'
 import { UsageError } from '../../errors'
 import { scaffold, scaffoldFiles } from '../../template'
 import { writeHarnessFiles } from '../../harness'
+import { DEV_ENV_FILE, writeDevEnv } from '../../dev-env'
 import type { Command } from '../types'
 
 export const appInit: Command = {
@@ -38,8 +39,29 @@ export const appInit: Command = {
     ).length
     ctx.output.note(`  SDK vendored into src/frontera/ (${vendored} files) — imports resolve by alias`)
 
+    // 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
+    // project never received it, so every app built from scratch rendered
+    // empty — and an agent looking at a page with no numbers on it cannot see
+    // that one of the numbers is wrong.
+    //
+    // 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`,
+    )
+
     return {
-      data: { name, path: target, harnessFiles: harness.written, vendoredSdkFiles: vendored },
+      data: {
+        name,
+        path: target,
+        harnessFiles: harness.written,
+        vendoredSdkFiles: vendored,
+        devEnvWritten: devEnv.written,
+      },
       text: [
         `Scaffolded ${name}`,
         '',

package/src/commands/app/pull.ts

@@ -1,43 +1,12 @@
-import { mkdirSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
-import { gunzipSync } from 'node:zlib'
+import { join } from 'node:path'
 
 import { AppsApi } from '../../api/apps-api'
 import { CliError, UsageError } from '../../errors'
 import { healProject } from '../../heal'
 import { dirtyFiles, writeState } from '../../project'
+import { DEV_ENV_FILE, writeDevEnv } from '../../dev-env'
 import { flagBool, type Command } from '../types'
-
-/** Unpack a gzipped ustar archive onto disk. */
-function unpackTo(dir: string, gz: Uint8Array): number {
-  const buf = new Uint8Array(gunzipSync(Buffer.from(gz)))
-  const dec = new TextDecoder()
-  const readStr = (start: number, len: number) => {
-    let end = start
-    while (end < start + len && buf[end] !== 0) end++
-    return dec.decode(buf.subarray(start, end))
-  }
-  let off = 0
-  let count = 0
-  while (off + 512 <= buf.length) {
-    const name = readStr(off, 100)
-    if (name === '') break
-    const prefix = readStr(off + 345, 155)
-    const size = parseInt(readStr(off + 124, 12).trim() || '0', 8)
-    const dataStart = off + 512
-    if (buf[off + 156] === 0x30 || buf[off + 156] === 0) {
-      const rel = (prefix ? `${prefix}/${name}` : name).replace(/^\.?\//, '')
-      if (rel && !rel.split('/').includes('..')) {
-        const full = join(dir, rel)
-        mkdirSync(dirname(full), { recursive: true })
-        writeFileSync(full, buf.subarray(dataStart, dataStart + size))
-        count++
-      }
-    }
-    off = dataStart + Math.ceil(size / 512) * 512
-  }
-  return count
-}
+import { unpackTo } from '../../untar'
 
 export const appPull: Command = {
   meta: {
@@ -134,9 +103,17 @@ export const appPull: Command = {
     // leaving the caller to discover it — see heal.ts.
     const { repairs } = healProject(dir)
 
+    // Same reason as `app init`: the dev host reads VITE_FRONTERA_TOKEN and
+    // 401s without it. `.env.local` is never packaged, so a pulled copy never
+    // 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)
+    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)'}`
     return {
-      data: { app: app.slug, appId: app.id, files: count, parentVersion, repairs },
+      data: { app: app.slug, appId: app.id, files: count, parentVersion, repairs, devEnvWritten: devEnv.written },
       text: repairs.length
         ? `${pulled}\nRepaired legacy packaging:\n${repairs.map((r) => `  ${r}`).join('\n')}`
         : pulled,

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

@@ -6,6 +6,11 @@ import { validateManifest } from '@frontera-sdk/automation'
 
 import { AutomationApi } from '../../api/automation-api'
 import { UsageError } from '../../errors'
+import { packDirectory } from '../../pack'
+import { automationInit } from './init'
+import { automationPull } from './pull'
+import { automationRun, automationRuns } from './run'
+import { findAutomationProjectRoot } from './project-root'
 import { formatBytes } from '../../packaging'
 import { table } from '../../table'
 import { flagBool, type Command, type CommandContext } from '../types'
@@ -152,10 +157,37 @@ const deploy: Command = {
     const bundle = new TextEncoder().encode(code)
     ctx.output.note(`  bundle ${formatBytes(bundle.byteLength)}`)
 
+    // The PROJECT root, not the entry file's directory. Packing `src/` omits
+    // package.json and tsconfig.json, so the pulled project cannot build — a
+    // first pass did exactly that and stored a one-member archive.
+    //
+    // `collectSourceFiles` excludes node_modules, build output, and `.env` /
+    // `.env.*` at any depth, which is what makes source retention safe to turn
+    // on: an FDE's project-local credential must never reach the bucket. That
+    // exclusion is deliberately not optional (see packaging.ts).
+    const projectRoot = findAutomationProjectRoot(resolve(file))
+    let source: Uint8Array | undefined
+    if (projectRoot) {
+      source = packDirectory(projectRoot, ctx.output, 'source').tgz
+    } else {
+      // Degrade honestly rather than refuse. Authoring inside this monorepo is
+      // still supported and simply cannot retain source — there is no
+      // package.json between the file and a workspace root, and packing a
+      // workspace root would upload the whole monorepo. Saying so is the point:
+      // the alternative is a version that silently cannot be pulled.
+      ctx.output.note(
+        '  warning: no automation project found (no package.json above '
+          + `${file}, or the nearest one is a workspace root) — deploying WITHOUT `
+          + 'source, so `frontera automation pull` will not work for this version. '
+          + 'Run `frontera automation init` to author in a project.',
+      )
+    }
+
     const client = new AutomationApi(ctx.apiUrl, ctx.token)
     const result = await client.deploy(slug, {
       manifest,
       bundle,
+      source,
       promote: !flagBool(ctx, 'no-promote'),
     })
 
@@ -243,10 +275,15 @@ const versions: Command = {
         rows.length === 0
           ? `No versions deployed for ${slug}.`
           : table(
-              ['live', 'version', 'digest', 'size', 'created'],
+              ['live', 'version', 'state', 'digest', 'size', 'created'],
               rows.map((v) => [
                 v.id === liveVersionId ? '*' : '',
                 String(v.version),
+                // A retired version is still LISTED — the row is the record that
+                // the version number was used, and numbers are never reused. But
+                // listing it unmarked implies it can be pulled or promoted, and
+                // it can be neither: retention deleted its bundle and source.
+                v.retiredAt ? 'retired' : '',
                 v.contentDigest.slice(0, 12),
                 formatBytes(v.totalBytes),
                 v.createdAt,
@@ -322,4 +359,8 @@ export const automationCommands: Command[] = [
   promote,
   enabledCommand('enable', 'Resume scheduled execution'),
   enabledCommand('disable', 'Stop scheduled execution immediately — the kill switch'),
+  automationRun,
+  automationRuns,
+  automationPull,
+  automationInit,
 ]

package/src/commands/automation/init.ts

@@ -0,0 +1,52 @@
+import { join } from 'node:path'
+
+import { automationScaffoldFiles, scaffoldAutomation } from '../../automation-template'
+import { UsageError } from '../../errors'
+import type { Command } from '../types'
+
+export const automationInit: Command = {
+  meta: {
+    noun: 'automation',
+    verb: 'init',
+    args: [{
+      name: 'name',
+      required: true,
+      description: 'directory and automation slug for the new project',
+    }],
+    flags: { dir: 'string' },
+    summary: 'Scaffold a new automation project',
+    examples: ['frontera automation init daily-digest'],
+    // 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 automation init <name>')
+
+    const base = typeof ctx.flags.dir === 'string' ? ctx.flags.dir : ctx.cwd
+    const target = join(base, name)
+    scaffoldAutomation(target, name)
+
+    // Reported because it is the one surprising thing about the tree: an agent or
+    // engineer who does not know the SDK is vendored will try to "fix" the
+    // imports into a package dependency that resolves nowhere.
+    const vendored = Object.keys(automationScaffoldFiles(name))
+      .filter((f) => f.startsWith('src/frontera/')).length
+    ctx.output.note(
+      `  SDK vendored into src/frontera/ (${vendored} files) — imports resolve by tsconfig paths`,
+    )
+
+    return {
+      data: { name, path: target, vendoredSdkFiles: vendored },
+      text: [
+        `Scaffolded ${name}`,
+        '',
+        `  cd ${name}`,
+        '  bun install',
+        '  bun run typecheck',
+        '  frontera automation deploy src/index.ts',
+      ].join('\n'),
+    }
+  },
+}

package/src/commands/automation/project-root.ts

@@ -0,0 +1,58 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, parse } from 'node:path'
+
+/**
+ * The project directory to pack as an automation's source, or null.
+ *
+ * Walks up from the entry file to the nearest `package.json`. Two rules, and both
+ * exist because the obvious implementations are actively harmful:
+ *
+ *   - NOT the entry file's own directory. `src/index.ts` would pack `src/` and
+ *     omit `package.json` and `tsconfig.json` — so a pulled project would
+ *     contain a lone source file and could not build. Measured: a first pass did
+ *     exactly this and stored a one-member archive.
+ *
+ *   - NOT a workspace root. An automation authored inside this monorepo has no
+ *     `package.json` between it and the repo root, so an unguarded walk would
+ *     pack the WHOLE monorepo into a bucket. A `package.json` declaring
+ *     `workspaces` is therefore refused as a root.
+ *
+ * Returning null rather than throwing is deliberate: authoring inside the
+ * monorepo is still supported, it simply cannot retain source. The caller says
+ * so out loud and deploys anyway, and `pull` reports the missing source
+ * actionably. Refusing would break a workflow that works.
+ */
+export function findAutomationProjectRoot(entryFile: string): string | null {
+  const { root } = parse(entryFile)
+  let dir = dirname(entryFile)
+
+  while (true) {
+    const manifest = join(dir, 'package.json')
+    if (existsSync(manifest)) {
+      let parsed: unknown
+      try {
+        parsed = JSON.parse(readFileSync(manifest, 'utf8'))
+      } catch {
+        // Cannot verify this is NOT a workspace root, and the hazard being
+        // guarded is uploading an entire monorepo. Packing it and walking past it
+        // both risk that — packing directly, walking past by reaching a parent
+        // project the author never meant to publish. So refuse: deploy proceeds
+        // without source and says so.
+        return null
+      }
+      const isWorkspaceRoot =
+        typeof parsed === 'object'
+        && parsed !== null
+        && 'workspaces' in (parsed as Record<string, unknown>)
+      // A workspace root is never the answer. Stop rather than continue: every
+      // ancestor above it is even less likely to be the project, and walking on
+      // risks finding some unrelated package.json further up the filesystem.
+      if (isWorkspaceRoot) return null
+      return dir
+    }
+    if (dir === root) return null
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}

package/src/commands/automation/pull.ts

@@ -0,0 +1,124 @@
+import { existsSync, mkdirSync, readdirSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { AutomationApi } from '../../api/automation-api'
+import { UsageError } from '../../errors'
+import { unpackTo } from '../../untar'
+import { flagBool, type Command } from '../types'
+
+/** Split `slug` or `slug@3` into its parts. Exported for its own tests. */
+export function parseTarget(raw: string): { slug: string; version: number | null } {
+  const at = raw.lastIndexOf('@')
+  if (at === -1) {
+    if (!raw) throw new UsageError('missing slug', 'frontera automation pull <slug>[@version]')
+    return { slug: raw, version: null }
+  }
+  const slug = raw.slice(0, at)
+  const rest = raw.slice(at + 1)
+  if (!slug) throw new UsageError('missing slug', 'frontera automation pull <slug>[@version]')
+  if (!/^\d+$/.test(rest)) {
+    // Not silently falling back to latest: handing back a different version than
+    // the one named is the failure mode this phase exists to prevent.
+    throw new UsageError(
+      `version must be a number, got "${rest}"`,
+      'frontera automation pull <slug>@3',
+    )
+  }
+  return { slug, version: Number(rest) }
+}
+
+/**
+ * Where a pull writes, refusing to clobber.
+ *
+ * There are no server-side drafts for automations, so uncommitted local work a
+ * pull overwrites is gone. Refusing by default and requiring `--force` puts that
+ * decision in the author's hands. `readdirSync` counts dotfiles, so a directory
+ * holding only a `.git` is non-empty — which is exactly the case where clobbering
+ * costs the most.
+ *
+ * `resolve`, not `join`: `join(cwd, '/tmp/x')` yields `<cwd>/tmp/x`, so an
+ * absolute `--dir` landed inside the working directory. Measured — a pull with
+ * `--dir /tmp/pulled` wrote to `/tmp/pulled/tmp/pulled`. Exported for its own
+ * tests.
+ */
+export function resolveTargetDir(
+  cwd: string,
+  slug: string,
+  dirFlag: string | undefined,
+  force: boolean,
+): string {
+  // `--dir` is a GLOBAL flag: `main.ts` sets `cwd` to it before any command
+  // runs. So when it is present the target IS `cwd`, and resolving its VALUE
+  // again here appended it twice — the documented `--dir ./recovered` wrote to
+  // `./recovered/recovered`. Only its PRESENCE is signal; the value is already
+  // accounted for. An absolute flag hid this, because resolving an absolute path
+  // a second time is idempotent.
+  const target = dirFlag === undefined ? resolve(cwd, slug) : resolve(cwd)
+  if (!force && existsSync(target) && readdirSync(target).length > 0) {
+    throw new UsageError(
+      `${target} is not empty`,
+      'pull into a new directory, or pass --force to overwrite',
+    )
+  }
+  return target
+}
+
+export const automationPull: Command = {
+  meta: {
+    noun: 'automation',
+    verb: 'pull',
+    args: [{
+      name: 'slug[@version]',
+      required: true,
+      description: 'automation slug, optionally pinned to a version',
+    }],
+    flags: { dir: 'string', force: 'boolean' },
+    summary: 'Hydrate an editable project from a deployed version',
+    examples: [
+      'frontera automation pull daily-digest',
+      'frontera automation pull daily-digest@3 --dir ./recovered',
+    ],
+  },
+
+  async run(ctx) {
+    const raw = ctx.positional[0]
+    if (!raw) throw new UsageError('missing <slug>', 'frontera automation pull <slug>[@version]')
+    const { slug, version } = parseTarget(raw)
+
+    const client = new AutomationApi(ctx.apiUrl, ctx.token)
+
+    // "Latest" is resolved against the version list rather than by inventing a
+    // server endpoint for it — `versions` already exists and is authoritative.
+    let resolved = version
+    if (resolved === null) {
+      const list = await client.versions(slug)
+      if (list.length === 0) throw new UsageError(`${slug} has no versions`, 'deploy it first')
+      resolved = Math.max(...list.map((v) => v.version))
+    }
+
+    // Refuse BEFORE downloading. Discovering the directory is occupied after a
+    // network round trip wastes it, and worse, invites a --force retry that the
+    // author has not actually thought about.
+    const target = resolveTargetDir(
+      ctx.cwd,
+      slug,
+      typeof ctx.flags.dir === 'string' ? ctx.flags.dir : undefined,
+      flagBool(ctx, 'force'),
+    )
+
+    const gz = await client.downloadSource(slug, resolved)
+    mkdirSync(target, { recursive: true })
+    const count = unpackTo(target, gz)
+
+    return {
+      data: { slug, version: resolved, path: target, files: count },
+      text: [
+        `Pulled ${slug} v${resolved} into ${target} (${count} files)`,
+        '',
+        `  cd ${target}`,
+        '  bun install',
+        '  frontera automation deploy src/index.ts',
+      ].join('\n'),
+    }
+  },
+}