@frontera-sdk/cli 0.1.0

package/src/registry.ts

@@ -0,0 +1,62 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import type { RegistryItem } from './api/registry-api'
+
+export type { RegistryFile, RegistryItem } from './api/registry-api'
+
+export interface WriteResult {
+  written: string[]
+  skipped: string[]
+  npmDependencies: string[]
+}
+
+/**
+ * Write resolved items into a project.
+ *
+ * Existing files are SKIPPED unless `force` — components are owned source once
+ * copied, so an author who has edited `button.tsx` must not lose that work to
+ * an unrelated `frontera app add card` that happens to pull button along as a
+ * dependency. Refreshing on purpose is `--force`.
+ */
+export function writeRegistryItems(
+  projectDir: string,
+  items: RegistryItem[],
+  opts: { force?: boolean; srcDir?: string } = {},
+): WriteResult {
+  const srcDir = opts.srcDir ?? 'src'
+  const written: string[] = []
+  const skipped: string[] = []
+  const npmDependencies = new Set<string>()
+
+  for (const item of items) {
+    for (const dep of item.dependencies) npmDependencies.add(dep)
+    for (const file of item.files) {
+      const dest = join(projectDir, srcDir, file.path)
+      if (existsSync(dest) && !opts.force) {
+        skipped.push(file.path)
+        continue
+      }
+      mkdirSync(dirname(dest), { recursive: true })
+      writeFileSync(dest, file.content)
+      written.push(file.path)
+    }
+  }
+
+  return { written, skipped, npmDependencies: [...npmDependencies] }
+}
+
+/** npm dependencies an item needs that the project does not already declare. */
+export function missingDependencies(projectDir: string, required: string[]): string[] {
+  const pkgPath = join(projectDir, 'package.json')
+  if (!existsSync(pkgPath)) return required
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as {
+    dependencies?: Record<string, string>
+    devDependencies?: Record<string, string>
+  }
+  const declared = new Set([
+    ...Object.keys(pkg.dependencies ?? {}),
+    ...Object.keys(pkg.devDependencies ?? {}),
+  ])
+  return required.filter((d) => !declared.has(d))
+}

package/src/secrets.ts

@@ -0,0 +1,69 @@
+import { readFileSync } from 'node:fs'
+
+import { UsageError } from './errors'
+
+export interface SecretSpec {
+  /** `literal` — the value itself; `ref` — the name of a workspace secret. */
+  kind: 'literal' | 'ref'
+  value: string
+}
+
+/**
+ * How a secret enters the CLI.
+ *
+ * Never as an inline flag value. `--api-key hunter2` lands in process
+ * listings and shell history, and a CLI that accepts it will have it used, so
+ * the raw form is refused rather than merely discouraged.
+ *
+ *   name@-            read from stdin
+ *   name@./file       read from a file
+ *   name=ref:my-key   reference an existing workspace secret
+ *
+ * The reference form is preferred: the value never enters a document, a flag
+ * or a shell, and the workspace secret store already keeps a
+ * create/update/delete/resolve/rotate audit trail.
+ */
+export async function readSecret(spec: string): Promise<{ name: string; secret: SecretSpec }> {
+  const at = spec.indexOf('@')
+  const eq = spec.indexOf('=')
+
+  if (at > 0 && (eq === -1 || at < eq)) {
+    const name = spec.slice(0, at)
+    const source = spec.slice(at + 1)
+    return { name, secret: { kind: 'literal', value: await readSecretValue(source) } }
+  }
+
+  if (eq > 0) {
+    const name = spec.slice(0, eq)
+    const value = spec.slice(eq + 1)
+    if (value.startsWith('ref:')) {
+      return { name, secret: { kind: 'ref', value: value.slice('ref:'.length) } }
+    }
+    throw new UsageError(
+      `refusing an inline secret value for "${name}"`,
+      `pass it as ${name}@- (stdin), ${name}@./file, or ${name}=ref:<workspace-secret>`,
+    )
+  }
+
+  throw new UsageError(
+    `could not read a secret from "${spec}"`,
+    'use name@- , name@./file , or name=ref:<workspace-secret>',
+  )
+}
+
+/** Read a secret's bytes from stdin (`-`) or a file path. */
+export async function readSecretValue(source: string): Promise<string> {
+  const path = source.startsWith('@') ? source.slice(1) : source
+  if (path === '-') return readStdin()
+  try {
+    return readFileSync(path, 'utf8')
+  } catch {
+    throw new UsageError(`could not read ${path}`, 'check the path, or pipe the value in with @-')
+  }
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Uint8Array[] = []
+  for await (const chunk of Bun.stdin.stream()) chunks.push(chunk)
+  return Buffer.concat(chunks).toString('utf8')
+}

package/src/table.ts

@@ -0,0 +1,47 @@
+/**
+ * A plain, aligned table for human output.
+ *
+ * Every list command prints an identifier the caller is expected to pass to
+ * the next command, and without a header there is no way to tell which column
+ * that is — `blueprint list` printed the api name beside the display name and
+ * a reader could only guess which one `get` wanted.
+ *
+ * Columns are padded to their content, never truncated: an id cut to fit is an
+ * id that cannot be copied, which defeats the point of printing it. Wide rows
+ * wrap in the terminal instead, which is recoverable.
+ *
+ * Human output only. `--json` returns the payload, and anything parsing this
+ * text should be using that instead.
+ */
+export function table(
+  headers: string[],
+  rows: string[][],
+  /**
+   * Per-column cap, by index. Only for free text.
+   *
+   * A skill description can run to 600 characters, which wrapped every row
+   * and destroyed the alignment the table exists for. Identifiers must never
+   * be given a cap — one cut to fit cannot be copied, which defeats printing
+   * it — so this is opt-in per column rather than a global width.
+   */
+  maxWidths: Array<number | undefined> = [],
+): string {
+  if (rows.length === 0) return ''
+
+  const clip = (value: string, i: number): string => {
+    const max = maxWidths[i]
+    if (!max || value.length <= max) return value
+    return `${value.slice(0, max - 1).trimEnd()}…`
+  }
+
+  const clipped = rows.map((r) => r.map((cell, i) => clip(cell ?? '', i)))
+  const widths = headers.map((h, i) =>
+    Math.max(h.length, ...clipped.map((r) => (r[i] ?? '').length)),
+  )
+  rows = clipped
+
+  const line = (cells: string[]) =>
+    `  ${cells.map((c, i) => (i === cells.length - 1 ? c : c.padEnd(widths[i]!))).join('  ').trimEnd()}`
+
+  return [line(headers.map((h) => h.toUpperCase())), ...rows.map(line)].join('\n')
+}

package/src/tar.ts

@@ -0,0 +1,73 @@
+import { gzipSync } from 'node:zlib'
+
+import type { SourceFile } from './packaging'
+
+/**
+ * Write a gzipped USTAR archive.
+ *
+ * ustar specifically, not GNU: the service's reader parses ustar headers only,
+ * and GNU's long-name ('L') entries would be skipped. The service rejects any
+ * path over 255 chars rather than dropping it, so an over-long path fails
+ * loudly at upload instead of silently vanishing from the bundle.
+ */
+export const MAX_USTAR_PATH = 255
+
+export function createTarGz(files: SourceFile[]): Uint8Array {
+  const enc = new TextEncoder()
+  const blocks: Uint8Array[] = []
+
+  for (const file of files) {
+    if (file.rel.length > MAX_USTAR_PATH) {
+      throw new Error(
+        `path too long for ustar (${file.rel.length} > ${MAX_USTAR_PATH}): ${file.rel}`,
+      )
+    }
+
+    const header = new Uint8Array(512)
+    const write = (off: number, value: string, len: number) =>
+      header.set(enc.encode(value.slice(0, len)), off)
+
+    // ustar splits a long path across prefix(155) + name(100).
+    let name = file.rel
+    let prefix = ''
+    if (name.length > 100) {
+      const cut = name.lastIndexOf('/', 100)
+      if (cut <= 0) throw new Error(`cannot split path for ustar: ${file.rel}`)
+      prefix = name.slice(0, cut)
+      name = name.slice(cut + 1)
+    }
+
+    write(0, name, 100)
+    write(100, '0000644', 8) // mode
+    write(108, '0000000', 8) // uid
+    write(116, '0000000', 8) // gid
+    write(124, file.bytes.byteLength.toString(8).padStart(11, '0'), 12)
+    write(136, Math.floor(Date.now() / 1000).toString(8).padStart(11, '0'), 12)
+    write(148, '        ', 8) // checksum placeholder (spaces during calc)
+    header[156] = 0x30 // '0' regular file
+    write(257, 'ustar', 6)
+    write(263, '00', 2)
+    write(345, prefix, 155)
+
+    // Header checksum: sum of all bytes with the checksum field as spaces.
+    let sum = 0
+    for (const b of header) sum += b
+    write(148, `${sum.toString(8).padStart(6, '0')}\0 `, 8)
+
+    blocks.push(header)
+    const padded = new Uint8Array(Math.ceil(file.bytes.byteLength / 512) * 512)
+    padded.set(file.bytes)
+    blocks.push(padded)
+  }
+
+  blocks.push(new Uint8Array(1024)) // two zero blocks = EOF
+
+  const total = blocks.reduce((n, b) => n + b.length, 0)
+  const tar = new Uint8Array(total)
+  let off = 0
+  for (const b of blocks) {
+    tar.set(b, off)
+    off += b.length
+  }
+  return new Uint8Array(gzipSync(Buffer.from(tar)))
+}