@frontera-sdk/cli 0.1.0

package/src/commands/app/promote.ts

@@ -0,0 +1,31 @@
+import { AppsApi } from '../../api/apps-api'
+import { UsageError } from '../../errors'
+import { projectApp, requireProjectFrom } from './shared'
+import type { Command } from '../types'
+
+export const appPromote: Command = {
+  meta: {
+    noun: 'app',
+    verb: 'promote',
+    args: [{ name: 'version', required: true, description: 'version to make live' }],
+    flags: {},
+    summary: 'Move the live pointer to an already-published version',
+    examples: ['frontera app promote 1.4.0'],
+    needsProject: true,
+  },
+
+  async run(ctx) {
+    const version = ctx.positional[0]
+    if (!version) throw new UsageError('missing <version>', 'frontera app promote <version>')
+
+    const project = requireProjectFrom(ctx)
+    const client = new AppsApi(ctx.apiUrl, ctx.token)
+    const app = await projectApp(client, project)
+    const res = await client.deploy(app.id, version)
+
+    return {
+      data: { app: app.slug, appId: app.id, deployedVersion: res.deployedVersion },
+      text: `Promoted ${app.slug}@${res.deployedVersion}`,
+    }
+  },
+}

package/src/commands/app/pull.ts

@@ -0,0 +1,145 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { gunzipSync } from 'node:zlib'
+
+import { AppsApi } from '../../api/apps-api'
+import { CliError, UsageError } from '../../errors'
+import { healProject } from '../../heal'
+import { dirtyFiles, writeState } from '../../project'
+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
+}
+
+export const appPull: Command = {
+  meta: {
+    noun: 'app',
+    verb: 'pull',
+    args: [{ name: 'app[@version]', required: true, description: 'app slug or id, optionally pinned to a version' }],
+    flags: { draft: 'boolean', force: 'boolean' },
+    summary:
+      'Hydrate a working tree from a published version or your saved draft, into the current directory or --dir',
+    examples: [
+      'frontera app pull shipments-console --dir ~/apps/shipments-console',
+      'frontera app pull shipments-console',
+      'frontera app pull shipments-console@1.4.0',
+      'frontera app pull shipments-console --draft',
+    ],
+    // Pull hydrates a directory that is usually empty, so it must not require
+    // an existing project — but it is the command that most needs `--dir`.
+    //
+    // It unpacks INTO that directory and never creates a `<dir>/<slug>`
+    // beneath it. The summary says so because two other texts once assumed
+    // otherwise and sent an agent hunting for a subdirectory that was never
+    // made; `--dir` is first in the examples for the same reason.
+    optionalProject: true,
+  },
+
+  async run(ctx) {
+    const target = ctx.positional[0]
+    if (!target) throw new UsageError('missing <app>', 'frontera app pull <app>[@version]')
+    const [slug, pinned] = target.split('@')
+
+    const dir = typeof ctx.flags.dir === 'string' ? ctx.flags.dir : ctx.cwd
+
+    // Refuse before destroying. Inside a Computer sandbox there is often no
+    // git to recover from, so erring toward refusal costs one --force and
+    // erring the other way costs someone's afternoon.
+    const dirty = dirtyFiles(dir)
+    if (dirty.length > 0 && !flagBool(ctx, 'force')) {
+      const shown = dirty.slice(0, 10).map((f) => `  ${f}`).join('\n')
+      throw new CliError(
+        `refusing to pull: ${dirty.length} file(s) in the working tree would be overwritten\n${shown}` +
+          (dirty.length > 10 ? `\n  …and ${dirty.length - 10} more` : ''),
+        { code: 'CONFLICT', hint: 'commit or stash them, or re-run with --force' },
+      )
+    }
+
+    const client = new AppsApi(ctx.apiUrl, ctx.token)
+    // Resolve, never ensure: pulling an unknown or renamed slug must fail,
+    // not quietly create an empty app to pull nothing from.
+    const app = await client.resolveApp(slug!)
+
+    let bytes: Uint8Array
+    let parentVersion: string | null
+
+    if (flagBool(ctx, 'draft')) {
+      const draft = await client.downloadDraft(app.id).catch(() => null)
+      if (!draft) {
+        // The generic NOT_FOUND hint ("list the resource first") is wrong here:
+        // the app resolved fine, it simply has no source stored. That happens
+        // for an app created in the console and never deployed from the CLI.
+        throw new CliError(`no source stored for ${app.slug}`, {
+          code: 'NOT_FOUND',
+          hint: 'this app has no saved draft and no deployed version — start from `frontera app init <name>`',
+        })
+      }
+      bytes = draft.bytes
+      parentVersion = draft.parentVersion
+    } else {
+      const versions = await client.listVersions(app.id)
+      const chosen = pinned
+        ? versions.find((v) => v.version === pinned)
+        : versions.find((v) => v.deployed) ?? versions[0]
+      if (!chosen) {
+        // NOT `app versions`: that needs a project, and the directory being
+        // pulled into is empty by definition — the hint would send the caller
+        // to a command that cannot run where they are.
+        throw new CliError(`no ${pinned ?? 'deployed'} version to pull for ${slug}`, {
+          code: 'NOT_FOUND',
+          hint: pinned
+            ? `run \`frontera app list\` to see apps, or omit @${pinned} to take the live one`
+            : `this app has never been deployed — pull the saved draft with \`frontera app pull ${slug} --draft\``,
+        })
+      }
+      bytes = await client.downloadSource(app.id, chosen.version)
+      parentVersion = chosen.version
+    }
+
+    const count = unpackTo(dir, bytes)
+    writeState(dir, { appId: app.id, parentVersion })
+
+    // Pull's contract is "give me a working copy", and a copy that cannot
+    // `bun install` is not one. Apps stored by an older toolchain carry
+    // `@frontera-sdk/*` dependencies pinned to absolute paths on the machine that
+    // published them, and no dev host. Repair on the way out rather than
+    // leaving the caller to discover it — see heal.ts.
+    const { repairs } = healProject(dir)
+
+    const pulled = `Pulled ${count} files from ${app.slug}${parentVersion ? `@${parentVersion}` : ' (draft)'}`
+    return {
+      data: { app: app.slug, appId: app.id, files: count, parentVersion, repairs },
+      text: repairs.length
+        ? `${pulled}\nRepaired legacy packaging:\n${repairs.map((r) => `  ${r}`).join('\n')}`
+        : pulled,
+    }
+  },
+}

package/src/commands/app/save.ts

@@ -0,0 +1,36 @@
+import { AppsApi } from '../../api/apps-api'
+import { packDirectory } from '../../pack'
+import { writeAppId, writeState } from '../../project'
+import { requireProjectFrom } from './shared'
+import type { Command } from '../types'
+
+export const appSave: Command = {
+  meta: {
+    noun: 'app',
+    verb: 'save',
+    args: [],
+    flags: {},
+    summary: 'Store the working tree as your draft, without building',
+    examples: ['frontera app save'],
+    needsProject: true,
+  },
+
+  async run(ctx) {
+    const project = requireProjectFrom(ctx)
+    const client = new AppsApi(ctx.apiUrl, ctx.token)
+
+    // save and deploy are the only verbs that may bring an app into
+    // existence; every read verb resolves instead.
+    const app = await client.ensureApp(project.slug, project.displayName, project.appId)
+    const { tgz } = packDirectory(project.root, ctx.output, 'packaged')
+    const res = await client.saveDraft(app.id, tgz, project.parentVersion)
+
+    writeState(project.root, { appId: app.id })
+    writeAppId(project.root, app.id)
+
+    return {
+      data: { app: app.slug, appId: app.id, fileCount: res.fileCount },
+      text: `Saved draft for ${app.slug} (${res.fileCount} files)`,
+    }
+  },
+}

package/src/commands/app/shared.ts

@@ -0,0 +1,25 @@
+import { AppsApi } from '../../api/apps-api'
+import { UsageError } from '../../errors'
+import type { AppProject } from '../../context'
+import type { CommandContext } from '../types'
+
+export function requireProjectFrom(ctx: CommandContext): AppProject {
+  if (!ctx.project) {
+    throw new UsageError(
+      'not in a Frontera app directory',
+      'cd into an app project, or run `frontera app init <name>`',
+    )
+  }
+  return ctx.project
+}
+
+/**
+ * The app this project belongs to, without creating one.
+ *
+ * Only `save` and `deploy` may bring an app into existence. A read-only verb
+ * that ensured instead would turn a typo, or a slug the platform had since
+ * renamed, into a brand new empty app.
+ */
+export function projectApp(client: AppsApi, project: AppProject) {
+  return client.resolveApp(project.appId ?? project.slug)
+}

package/src/commands/app/versions.ts

@@ -0,0 +1,38 @@
+import { AppsApi } from '../../api/apps-api'
+import { formatBytes } from '../../packaging'
+import { projectApp, requireProjectFrom } from './shared'
+import type { Command } from '../types'
+
+export const appVersions: Command = {
+  meta: {
+    noun: 'app',
+    verb: 'versions',
+    args: [],
+    flags: {},
+    summary: 'List published versions, newest first; * marks the live one',
+    examples: ['frontera app versions', 'frontera app versions --json'],
+    needsProject: true,
+  },
+
+  async run(ctx) {
+    const project = requireProjectFrom(ctx)
+    const client = new AppsApi(ctx.apiUrl, ctx.token)
+    const app = await projectApp(client, project)
+    const versions = await client.listVersions(app.id)
+
+    return {
+      data: versions,
+      text:
+        versions.length === 0
+          ? 'No versions published yet.'
+          : versions
+              .map(
+                (v) =>
+                  `${v.deployed ? '*' : ' '} ${v.version.padEnd(12)} ` +
+                  `parent=${(v.parentVersion ?? '-').padEnd(10)} ` +
+                  `${v.fileCount} files  ${formatBytes(v.totalBytes)}`,
+              )
+              .join('\n'),
+    }
+  },
+}

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

@@ -0,0 +1,325 @@
+import { existsSync, mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+import { validateManifest } from '@frontera-sdk/automation'
+
+import { AutomationApi } from '../../api/automation-api'
+import { UsageError } from '../../errors'
+import { formatBytes } from '../../packaging'
+import { table } from '../../table'
+import { flagBool, type Command, type CommandContext } from '../types'
+
+/** The one required argument every verb but `list` takes. */
+function requireSlug(ctx: CommandContext): string {
+  const slug = ctx.positional[0]
+  if (!slug) {
+    throw new UsageError(
+      'missing <slug>',
+      'run `frontera automation list` — then pass the slug of the one you mean',
+    )
+  }
+  return slug
+}
+
+/**
+ * Build the entry file, then read the manifest off the BUILT module.
+ *
+ * The artifact is the thing the runner will execute, so it is the thing worth
+ * inspecting: a manifest read from the source could differ from the one that
+ * ships. The cost is that importing it evaluates the module here, so anything
+ * an author does at import time runs on this machine — calling `automation()`
+ * and nothing else is the contract.
+ */
+export async function buildAndExtract(file: string): Promise<{
+  manifest: Record<string, unknown>
+  code: string
+}> {
+  const entry = resolve(file)
+  if (!existsSync(entry)) {
+    throw new UsageError(`no such file: ${file}`, 'pass the path to the automation entry file')
+  }
+
+  // `throw: false`. The default raises an AggregateError whose message is the
+  // bare string "Bundle failed" — no file, no reason — and it escapes as an
+  // INTERNAL_ERROR, telling the caller to RETRY a build that will never
+  // succeed. A build error is something the caller fixes, so it exits 2.
+  const built = await Bun.build({
+    entrypoints: [entry],
+    target: 'bun',
+    minify: false,
+    throw: false,
+  })
+  if (!built.success) {
+    throw new UsageError(
+      `could not build ${file}: ${built.logs.map((l) => l.message).join('; ')}`,
+      'fix the errors above, then run the command again',
+    )
+  }
+
+  const code = await built.outputs[0]!.text()
+
+  const dir = mkdtempSync(join(tmpdir(), 'frontera-automation-'))
+  try {
+    const bundle = join(dir, 'bundle.js')
+    await Bun.write(bundle, code)
+    const mod = (await import(bundle)) as { default?: { manifest?: unknown } }
+    const manifest = mod.default?.manifest
+
+    if (!manifest || typeof manifest !== 'object') {
+      throw new UsageError(
+        `${file} has no automation as its default export`,
+        'export the result of `automation({ … }, handler)` as the default export',
+      )
+    }
+    return { manifest: manifest as Record<string, unknown>, code }
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+/** How stale a registry poll may be before a deploy is worth warning about.
+ *  The runner's default interval is 15s, so a minute is several missed polls —
+ *  long enough not to fire on a restart, short enough to catch a dead runner. */
+const RUNNER_STALE_MS = 60_000
+
+/**
+ * The warning to print for a deploy, or null when a runner is clearly alive.
+ *
+ * Two distinct states, because the remedies differ: nothing has EVER polled
+ * (no runner is deployed in this environment at all) versus one polled but has
+ * since stopped (it is deployed and unhealthy).
+ */
+export function runnerWarningFor(
+  lastSeen: string | null | undefined,
+  now: number = Date.now(),
+): string | null {
+  // `undefined` and `null` are NOT the same thing here. `undefined` means the
+  // service did not send the field — an older build — and inferring "no runner"
+  // from silence would warn falsely against every environment predating it.
+  // `null` is the service explicitly saying nothing has ever polled.
+  if (lastSeen === undefined) return null
+  if (lastSeen === null) {
+    return 'no automation runner has ever polled this environment — the automation is stored and live, but nothing will execute it'
+  }
+  const age = now - new Date(lastSeen).getTime()
+  if (Number.isNaN(age) || age <= RUNNER_STALE_MS) return null
+  return `no automation runner has polled for ${Math.round(age / 1000)}s — the automation may not execute`
+}
+
+const deploy: Command = {
+  meta: {
+    noun: 'automation',
+    verb: 'deploy',
+    args: [
+      {
+        name: 'file',
+        required: true,
+        description: 'entry file whose default export is an `automation(…)`',
+      },
+    ],
+    flags: { 'no-promote': 'boolean' },
+    summary: 'Build and deploy an automation, promoting it live by default',
+    examples: [
+      'frontera automation deploy src/daily-digest.ts',
+      'frontera automation deploy src/daily-digest.ts --no-promote',
+    ],
+  },
+
+  async run(ctx) {
+    const file = ctx.positional[0]
+    if (!file) {
+      throw new UsageError('missing <file>', 'frontera automation deploy <file>')
+    }
+
+    const { manifest, code } = await buildAndExtract(file)
+
+    // A courtesy check — the service validates again and is authoritative. It
+    // earns its place by failing before the upload, and by printing the
+    // warnings the service discards: an unknown key is not an error, so
+    // `concurrancy: 100` would otherwise deploy "successfully" and run at the
+    // default of 1 with nothing on screen to say so.
+    const check = validateManifest(manifest)
+    for (const warning of check.warnings) ctx.output.note(`  warning: ${warning}`)
+    if (!check.valid) {
+      throw new UsageError(
+        `invalid manifest: ${check.errors.join('; ')}`,
+        'fix the manifest passed to `automation()`, then deploy again',
+      )
+    }
+
+    const slug = manifest.name as string
+    const bundle = new TextEncoder().encode(code)
+    ctx.output.note(`  bundle ${formatBytes(bundle.byteLength)}`)
+
+    const client = new AutomationApi(ctx.apiUrl, ctx.token)
+    const result = await client.deploy(slug, {
+      manifest,
+      bundle,
+      promote: !flagBool(ctx, 'no-promote'),
+    })
+
+    // A deploy into an environment with no runner succeeds at every layer —
+    // the bundle is stored, the version is live, `list` says ENABLED — and
+    // nothing ever fires, because nothing polls the registry. `runnerLastSeenAt`
+    // is the only signal that distinguishes "scheduled" from "scheduled and
+    // will actually run", so say it out loud rather than reporting success.
+    const runnerWarning = runnerWarningFor(result.runnerLastSeenAt)
+    if (runnerWarning) ctx.output.note(`  warning: ${runnerWarning}`)
+
+    return {
+      data: { slug, ...result },
+      // `result.promoted` rather than the flag: the service decides, and
+      // reporting the request instead of the outcome is how a CLI comes to
+      // claim something is live when it is not.
+      text:
+        `Deployed ${slug} v${result.version}` +
+        (result.promoted
+          ? ' and promoted it'
+          : ` (not promoted — use \`frontera automation promote ${slug} ${result.version}\`)`),
+    }
+  },
+}
+
+const list: Command = {
+  meta: {
+    noun: 'automation',
+    verb: 'list',
+    args: [],
+    flags: {},
+    summary: 'List automations in this workspace',
+    examples: ['frontera automation list', 'frontera automation list --json'],
+  },
+
+  async run(ctx) {
+    const rows = await new AutomationApi(ctx.apiUrl, ctx.token).list()
+
+    return {
+      data: rows,
+      text:
+        rows.length === 0
+          ? 'No automations in this workspace.'
+          : // LIVE is its own column because it is a separate fact from
+            // ENABLED: a deploy with --no-promote leaves an automation enabled
+            // with nothing live, and nothing runs. One column would hide that.
+            table(
+              ['slug', 'enabled', 'live', 'description'],
+              rows.map((a) => [
+                a.slug,
+                String(a.enabled),
+                a.liveVersionId ? 'yes' : 'no',
+                a.description ?? '',
+              ]),
+              [undefined, undefined, undefined, 60],
+            ),
+    }
+  },
+}
+
+const versions: Command = {
+  meta: {
+    noun: 'automation',
+    verb: 'versions',
+    args: [{ name: 'slug', required: true, description: 'automation slug, from `frontera automation list`' }],
+    flags: {},
+    summary: 'List deployed versions, newest first; * marks the live one',
+    examples: ['frontera automation versions daily-digest'],
+  },
+
+  async run(ctx) {
+    const slug = requireSlug(ctx)
+    const client = new AutomationApi(ctx.apiUrl, ctx.token)
+
+    // Which version is LIVE is on the automation row, not on any version, so
+    // it takes a second read. Worth it: "which one is running" is the question
+    // this command exists to answer, and the alternative is making the caller
+    // run `list` and match a uuid by eye.
+    const [rows, all] = await Promise.all([client.versions(slug), client.list()])
+    const liveVersionId = all.find((a) => a.slug === slug)?.liveVersionId ?? null
+
+    return {
+      data: rows.map((v) => ({ ...v, live: v.id === liveVersionId })),
+      text:
+        rows.length === 0
+          ? `No versions deployed for ${slug}.`
+          : table(
+              ['live', 'version', 'digest', 'size', 'created'],
+              rows.map((v) => [
+                v.id === liveVersionId ? '*' : '',
+                String(v.version),
+                v.contentDigest.slice(0, 12),
+                formatBytes(v.totalBytes),
+                v.createdAt,
+              ]),
+            ),
+    }
+  },
+}
+
+const promote: Command = {
+  meta: {
+    noun: 'automation',
+    verb: 'promote',
+    args: [
+      { name: 'slug', required: true, description: 'automation slug' },
+      { name: 'version', required: true, description: 'version number, from `frontera automation versions`' },
+    ],
+    flags: {},
+    summary: 'Move the live pointer to an already-deployed version',
+    examples: ['frontera automation promote daily-digest 3'],
+  },
+
+  async run(ctx) {
+    const slug = requireSlug(ctx)
+    const raw = ctx.positional[1]
+    const version = Number(raw)
+    // Caught here rather than by the service so a typo costs no round trip,
+    // and so the message names the command that lists the real ones.
+    if (raw === undefined || !Number.isInteger(version)) {
+      throw new UsageError(
+        `version must be an integer, got ${raw === undefined ? '(none)' : `"${raw}"`}`,
+        `run \`frontera automation versions ${slug}\` to see the versions that exist`,
+      )
+    }
+
+    const result = await new AutomationApi(ctx.apiUrl, ctx.token).promote(slug, version)
+    return { data: result, text: `Promoted ${slug} to v${result.version}` }
+  },
+}
+
+/**
+ * `disable` is the kill switch, so it is its own verb rather than
+ * `enable --false`: stopping a misbehaving automation is done under pressure,
+ * and a flag is one more thing to get wrong.
+ */
+function enabledCommand(verb: 'enable' | 'disable', summary: string): Command {
+  const enabled = verb === 'enable'
+  return {
+    meta: {
+      noun: 'automation',
+      verb,
+      args: [{ name: 'slug', required: true, description: 'automation slug' }],
+      flags: {},
+      summary,
+      examples: [`frontera automation ${verb} daily-digest`],
+    },
+
+    async run(ctx) {
+      const slug = requireSlug(ctx)
+      const result = await new AutomationApi(ctx.apiUrl, ctx.token).setEnabled(slug, enabled)
+      return {
+        data: result,
+        text: `${enabled ? 'Enabled' : 'Disabled'} ${slug}`,
+      }
+    },
+  }
+}
+
+export const automationCommands: Command[] = [
+  deploy,
+  list,
+  versions,
+  promote,
+  enabledCommand('enable', 'Resume scheduled execution'),
+  enabledCommand('disable', 'Stop scheduled execution immediately — the kill switch'),
+]