@frontera-sdk/cli 0.1.0 → 1.43.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "0.1.0",
+  "version": "1.43.5",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -38,7 +38,9 @@
   },
   "dependencies": {
     "@frontera-sdk/automation": "0.1.0",
-    "@frontera-sdk/core": "0.1.0"
+    "@frontera-sdk/core": "0.1.0",
+    "gray-matter": "^4.0.3",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/api/apps-api.ts

@@ -105,6 +105,8 @@ export class AppsApi {
     source: Uint8Array
     manifest?: unknown
     promote: boolean
+    /** §4.4 — whether this tree had been rendered since its last source change. */
+    renderEvidence?: unknown
   }) {
     const form = new FormData()
     form.set('version', args.version)
@@ -113,7 +115,17 @@ export class AppsApi {
     form.set('source', new Blob([args.source], { type: 'application/gzip' }), 'src.tgz')
     if (args.manifest) form.set('manifest', JSON.stringify(args.manifest))
     form.set('promote', args.promote ? 'true' : 'false')
-    return this.multipart<{ version: string; promoted: boolean; fileCount: number; totalBytes: number }>(
+    if (args.renderEvidence) form.set('renderEvidence', JSON.stringify(args.renderEvidence))
+    return this.multipart<{
+      version: string
+      promoted: boolean
+      fileCount: number
+      totalBytes: number
+      /** Where a person opens this exact build — composed by the service,
+       *  which is the only side that knows the platform origin. */
+      previewUrl?: string
+      liveUrl?: string
+    }>(
       `/v1/platform-apps/${appId}/versions`,
       form,
     )

package/src/api/automation-api.ts

@@ -1,6 +1,8 @@
 import { FronteraClient } from '@frontera-sdk/core/client'
 import { FronteraError } from '@frontera-sdk/core/errors'
 
+import { CliError } from '../errors'
+
 /** A row of `GET /v1/automations/` — the shell, not any one version of it. */
 export interface AutomationSummary {
   id: string
@@ -40,6 +42,49 @@ export interface AutomationDeployResult {
   runnerLastSeenAt?: string | null
 }
 
+/** A row of `GET /v1/automations/<slug>/runs`. */
+export interface AutomationRunSummary {
+  id: string
+  status: string
+  triggerSource: string
+  triggeredBy: string | null
+  errorMessage: string | null
+  /** What the handler RETURNED. Null when it returned nothing, or has not finished. */
+  result: unknown
+  /** Billable ctx calls the run made. */
+  ctxCalls: number
+  startedAt: string
+  finishedAt: string | null
+  version: number
+}
+
+/** A row of `GET /v1/automations/runs/<id>/steps`. */
+export interface AutomationRunStep {
+  id: string
+  seq: number
+  kind: string
+  label: string
+  status: string
+  durationMs: number | null
+  /** The author's step name, or null when the row is a `ctx` call. */
+  stepName: string | null
+  /** The step this row ran inside, or null at the top level. */
+  parentStepId: string | null
+}
+
+/** `GET /v1/automations/registry-status`. */
+export interface RegistryStatus {
+  /** The generation the service has. */
+  generation: number
+  /**
+   * The generation a runner has REGISTERED with the broker, or null if none ever
+   * has. While this lags `generation`, a version deployed in between is not yet
+   * invocable.
+   */
+  registeredGeneration: number | null
+  lastPolledAt: string | null
+}
+
 /**
  * Client for the automation routes.
  *
@@ -80,6 +125,41 @@ export class AutomationApi {
     )
   }
 
+  /**
+   * Queue a run of the live version.
+   *
+   * Returns as soon as the invoke event is accepted — the run itself is
+   * asynchronous, which is why the caller polls `runs()` rather than being
+   * handed a result here. Ignores `enabled` on purpose: disable is a schedule
+   * kill switch, not a lock, so an operator can test a fix without re-arming the
+   * cron.
+   */
+  run(slug: string): Promise<{ slug: string; version: number; queued: boolean }> {
+    return this.client.request<{ slug: string; version: number; queued: boolean }>(
+      `/v1/automations/${encodeURIComponent(slug)}/run`,
+      { method: 'POST' },
+    )
+  }
+
+  registryStatus(): Promise<RegistryStatus> {
+    return this.client.request<RegistryStatus>('/v1/automations/registry-status')
+  }
+
+  runs(slug: string, limit?: number): Promise<AutomationRunSummary[]> {
+    const query = limit === undefined ? '' : `?limit=${limit}`
+    return this.client.request<AutomationRunSummary[]>(
+      `/v1/automations/${encodeURIComponent(slug)}/runs${query}`,
+    )
+  }
+
+  /** One run's trail. Workspace-scoped server-side, so a guessed id reads
+   *  nothing. */
+  runSteps(runId: string): Promise<AutomationRunStep[]> {
+    return this.client.request<AutomationRunStep[]>(
+      `/v1/automations/runs/${encodeURIComponent(runId)}/steps`,
+    )
+  }
+
   setEnabled(slug: string, enabled: boolean): Promise<{ slug: string; enabled: boolean }> {
     return this.client.request<{ slug: string; enabled: boolean }>(
       `/v1/automations/${encodeURIComponent(slug)}/enabled`,
@@ -95,13 +175,61 @@ export class AutomationApi {
    * way — its schema is `t.Unknown()` for exactly that reason — and sending the
    * string keeps this end honest about what a form field is.
    */
+  /** The stored source archive for a version, as gzip bytes. */
+  async downloadSource(slug: string, version: number): Promise<Uint8Array> {
+    const credential = this.client.config.credential
+    const res = await fetch(
+      `${this.client.config.apiBaseUrl}/v1/automations/${encodeURIComponent(slug)}`
+        + `/versions/${version}/source`,
+      {
+        headers: {
+          authorization: `Bearer ${credential.kind === 'apiKey' ? credential.key : credential.token}`,
+        },
+      },
+    )
+    if (!res.ok) {
+      // The service's message is the useful one — it distinguishes "no version"
+      // from "deployed before source retention", and the second names its remedy.
+      // Unwrapped from the envelope rather than passed through raw: a bare
+      // `throw new Error` renders as `[INTERNAL_ERROR] … {"error":true,…}`, which
+      // buries an actionable remedy inside JSON and mislabels a 404 the author
+      // caused as a platform fault. They would file a bug instead of reading the
+      // fix.
+      const body = await res.text()
+      let message = body
+      try {
+        const parsed = JSON.parse(body) as { message?: unknown }
+        if (typeof parsed.message === 'string') message = parsed.message
+      } catch {
+        // Not an envelope — keep the raw body, which is better than nothing.
+      }
+      // A hint is mandatory here — `error-hints.test.ts` scans for it, on the
+      // principle that every CLI-raised error names the next command. For a
+      // missing archive the next command is a redeploy from a local copy; for
+      // anything else, listing the versions tells the author what exists.
+      throw new CliError(message, {
+        code: res.status === 404 ? 'NOT_FOUND' : 'REQUEST_FAILED',
+        hint: res.status === 404
+          ? `frontera automation deploy <file>  (from a local copy of ${slug})`
+          : `frontera automation versions ${slug}`,
+      })
+    }
+    return new Uint8Array(await res.arrayBuffer())
+  }
+
   async deploy(
     slug: string,
-    args: { manifest: unknown; bundle: Uint8Array; promote: boolean },
+    args: { manifest: unknown; bundle: Uint8Array; source?: Uint8Array; promote: boolean },
   ): Promise<AutomationDeployResult> {
     const form = new FormData()
     form.set('manifest', JSON.stringify(args.manifest))
     form.set('bundle', new Blob([args.bundle], { type: 'application/javascript' }), 'bundle.js')
+    // The project the bundle was built FROM. Without it a deployed version can
+    // never be edited again — only the built output would survive. Absent when
+    // no project root was found; the caller has already warned about that.
+    if (args.source) {
+      form.set('source', new Blob([args.source], { type: 'application/gzip' }), 'src.tgz')
+    }
     // The service promotes unless the field is the literal "false".
     form.set('promote', args.promote ? 'true' : 'false')