@frontera-sdk/cli 1.44.0 → 1.45.0

package/src/kit.ts

@@ -0,0 +1,419 @@
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve as resolvePath } from 'node:path'
+
+import { CliError } from './errors'
+import vendored from './vendor/kit-assets.json'
+
+/**
+ * The authoring kit, as the CLI carries it.
+ *
+ * The bytes are pinned at build time (`scripts/sync-kit.ts`), so vendoring is
+ * offline and deterministic: the same CLI release writes the same instructions
+ * on any machine, on any day, with no network. That is what makes a lock file
+ * over them mean anything, and it is why upgrading a project's instructions is
+ * a CLI upgrade rather than a silent fetch at session start.
+ */
+export interface KitAssets {
+  kitVersion: string
+  cli: { minimum: string; maximumExclusive: string }
+  hosts: { codex: boolean; claudeCode: boolean }
+  assets: Record<string, string>
+  agentsBlock: string
+  claudeBlock: string
+  pluginManifests: { claudeCode: string; codex: string }
+  marketplaceManifests: { claudeCode: string; codex: string }
+}
+
+export const KIT: KitAssets = vendored as KitAssets
+
+export const LOCK_FILE = 'frontera.kit.lock.json'
+
+export const MANAGED_BEGIN = '<!-- frontera:begin — managed by `frontera kit`; edits here are replaced -->'
+export const MANAGED_END = '<!-- frontera:end -->'
+
+export interface KitLock {
+  schemaVersion: 1
+  kitVersion: string
+  cliVersion: string
+  /** Project-relative path → digest of the bytes this CLI wrote. */
+  files: Record<string, string>
+}
+
+export function digest(content: string): string {
+  return `sha256:${createHash('sha256').update(content).digest('hex').slice(0, 16)}`
+}
+
+/**
+ * The managed block, delimited and bounded.
+ *
+ * Whole-file generation is what makes a tool unwelcome in a repository someone
+ * else owns: a team's AGENTS.md carries their conventions, and replacing it to
+ * add five lines is not a trade they agreed to. Only what sits between the
+ * markers is ours.
+ */
+export function managedBlock(body: string): string {
+  return `${MANAGED_BEGIN}\n${body.trim()}\n${MANAGED_END}\n`
+}
+
+/** Insert or replace the managed block, leaving every other line where it is. */
+export function applyManagedBlock(existing: string | null, body: string): string {
+  const block = managedBlock(body)
+  if (existing === null || existing.trim() === '') return block
+
+  const begin = existing.indexOf(MANAGED_BEGIN)
+  const end = existing.indexOf(MANAGED_END)
+  if (begin !== -1 && end > begin) {
+    const before = existing.slice(0, begin)
+    const after = existing.slice(end + MANAGED_END.length).replace(/^\n/, '')
+    return `${before}${block}${after}`
+  }
+
+  // Appended, not prepended. The first lines of an AGENTS.md are where a team
+  // puts what matters most to them, and a tool that inserts itself above that
+  // has decided its own instructions outrank theirs.
+  const separator = existing.endsWith('\n') ? '\n' : '\n\n'
+  return `${existing}${separator}${block}`
+}
+
+/**
+ * Claude Code imports with `@AGENTS.md`.
+ *
+ * `./AGENTS.md` is a relative path Claude does not import — it reads as prose,
+ * so the contract silently never loads. Generated projects shipped exactly that
+ * line, which is why this repairs it rather than only writing it correctly for
+ * new projects.
+ */
+export function applyClaudeImport(existing: string | null, importLine: string): { content: string; repaired: boolean } {
+  const line = importLine.trim()
+  if (existing === null || existing.trim() === '') return { content: `${line}\n`, repaired: false }
+
+  const lines = existing.split('\n')
+  const broken = lines.findIndex((l) => l.trim() === './AGENTS.md' || l.trim() === '@./AGENTS.md')
+  if (broken !== -1) {
+    lines[broken] = line
+    return { content: lines.join('\n'), repaired: true }
+  }
+
+  if (lines.some((l) => l.trim() === line)) return { content: existing, repaired: false }
+
+  // An import has to be reachable, so it goes first — unlike the AGENTS.md
+  // block, this single line is the mechanism rather than instructions competing
+  // for a reader's attention.
+  return { content: `${line}\n\n${existing.replace(/^\n+/, '')}`, repaired: false }
+}
+
+export interface RenderedProject {
+  /** Generated files: fully owned by the kit, replaceable, digest-tracked. */
+  generated: Record<string, string>
+  /** Files the kit edits in place without owning. */
+  agentsMd: string | null
+  claudeMd: string | null
+}
+
+/** One source, two native projections — Codex reads neither host's other tree. */
+export function renderKit(kit: KitAssets = KIT): RenderedProject {
+  const generated: Record<string, string> = {}
+  for (const rel of Object.keys(kit.assets).sort()) {
+    const content = kit.assets[rel]!
+    if (kit.hosts.codex) generated[join('.agents', 'skills', rel)] = content
+    if (kit.hosts.claudeCode) generated[join('.claude', 'skills', rel)] = content
+  }
+  return {
+    generated,
+    agentsMd: kit.hosts.codex ? kit.agentsBlock : null,
+    claudeMd: kit.hosts.claudeCode ? kit.claudeBlock : null,
+  }
+}
+
+/**
+ * Write a complete, installable plugin marketplace to disk.
+ *
+ * This is what makes distribution possible without anything public. Both hosts
+ * accept a local DIRECTORY as a marketplace, and the CLI already carries every
+ * byte of the kit pinned at build time — so `frontera setup` can lay out a real
+ * marketplace on a machine with no checkout, no git remote and no network, and
+ * point the host at it. No repository to publish, no directory to submit to,
+ * and no customer's plugin tree leaving their machine.
+ *
+ * The layout mirrors the authoring repository exactly, because that is what the
+ * hosts validate against:
+ *
+ *     <root>/.claude-plugin/marketplace.json     Claude Code reads this
+ *     <root>/.agents/plugins/marketplace.json    Codex prefers this
+ *     <root>/plugin/.claude-plugin/plugin.json
+ *     <root>/plugin/.codex-plugin/plugin.json
+ *     <root>/plugin/skills/<name>/SKILL.md
+ *
+ * Fully rewritten each time: it is generated data with a version stamp, not
+ * somewhere anyone should be editing.
+ */
+export function materializeMarketplace(root: string, kit: KitAssets = KIT): string[] {
+  const files: Record<string, string> = {
+    [join('.claude-plugin', 'marketplace.json')]: kit.marketplaceManifests.claudeCode,
+    [join('.agents', 'plugins', 'marketplace.json')]: kit.marketplaceManifests.codex,
+    [join('plugin', '.claude-plugin', 'plugin.json')]: kit.pluginManifests.claudeCode,
+    [join('plugin', '.codex-plugin', 'plugin.json')]: kit.pluginManifests.codex,
+  }
+  for (const [rel, content] of Object.entries(kit.assets)) {
+    files[join('plugin', 'skills', rel)] = content
+  }
+
+  // A stamp, so a later `setup` can tell whether the tree on disk is this
+  // CLI's kit without diffing every file.
+  files['frontera-kit.json'] = `${JSON.stringify({ kitVersion: kit.kitVersion, materializedBy: 'frontera setup' }, null, 2)}\n`
+
+  const written: string[] = []
+  for (const [rel, content] of Object.entries(files).sort(([a], [b]) => a.localeCompare(b))) {
+    const dest = join(root, rel)
+    mkdirSync(dirname(dest), { recursive: true })
+    writeFileSync(dest, content)
+    written.push(rel)
+  }
+  return written
+}
+
+/** The kit version already materialized at `root`, if any. */
+export function materializedVersion(root: string): string | null {
+  const stamp = join(root, 'frontera-kit.json')
+  if (!existsSync(stamp)) return null
+  try {
+    return (JSON.parse(readFileSync(stamp, 'utf8')) as { kitVersion?: string }).kitVersion ?? null
+  } catch {
+    return null
+  }
+}
+
+export function readLock(root: string): KitLock | null {
+  const path = join(root, LOCK_FILE)
+  if (!existsSync(path)) return null
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as KitLock
+  } catch {
+    throw new CliError(`${LOCK_FILE} is not readable JSON`, {
+      code: 'GENERATED_FILE_CONFLICT',
+      hint: `delete ${LOCK_FILE} and run \`frontera kit vendor\` again`,
+    })
+  }
+}
+
+export interface WriteReport {
+  written: string[]
+  unchanged: string[]
+  conflicts: string[]
+  repaired: string[]
+}
+
+/**
+ * Write the generated tree.
+ *
+ * The rule that keeps this safe to re-run: a file is replaced only when its
+ * current bytes are the bytes this CLI last wrote. Anything else is a local
+ * edit, which is reported as a conflict rather than silently discarded —
+ * someone changed a skill for a reason, and finding out by losing it is the
+ * worst way to learn the tool regenerates.
+ */
+export function writeGenerated(
+  root: string,
+  generated: Record<string, string>,
+  lock: KitLock | null,
+  opts: { force?: boolean; onlyExisting?: boolean } = {},
+): WriteReport {
+  const report: WriteReport = { written: [], unchanged: [], conflicts: [], repaired: [] }
+
+  for (const [rel, content] of Object.entries(generated)) {
+    const dest = join(root, rel)
+    const exists = existsSync(dest)
+
+    if (!exists) {
+      // `sync` updates what vendoring already put here; it does not adopt a
+      // project that never opted in.
+      if (opts.onlyExisting) continue
+      mkdirSync(dirname(dest), { recursive: true })
+      writeFileSync(dest, content)
+      report.written.push(rel)
+      continue
+    }
+
+    const current = readFileSync(dest, 'utf8')
+    if (current === content) {
+      report.unchanged.push(rel)
+      continue
+    }
+
+    const recorded = lock?.files[rel]
+    if (opts.force || (recorded && digest(current) === recorded)) {
+      writeFileSync(dest, content)
+      report.written.push(rel)
+      continue
+    }
+
+    report.conflicts.push(rel)
+  }
+
+  return report
+}
+
+export function writeLock(root: string, generated: Record<string, string>, cliVersion: string): KitLock {
+  const lock: KitLock = {
+    schemaVersion: 1,
+    kitVersion: KIT.kitVersion,
+    cliVersion,
+    files: Object.fromEntries(Object.entries(generated).map(([rel, content]) => [rel, digest(content)])),
+  }
+  writeFileSync(join(root, LOCK_FILE), `${JSON.stringify(lock, null, 2)}\n`)
+  return lock
+}
+
+/** `1.45.0-dev` and `1.45.0` compare equal — the prerelease tail is noise here. */
+export function compareVersions(a: string, b: string): number {
+  const parse = (v: string) => v.split('-')[0]!.split('.').map((n) => Number.parseInt(n, 10) || 0)
+  const [x, y] = [parse(a), parse(b)]
+  for (let i = 0; i < 3; i += 1) {
+    if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) - (y[i] ?? 0)
+  }
+  return 0
+}
+
+export interface Compatibility {
+  compatible: boolean
+  cliVersion: string
+  required: { minimum: string; maximumExclusive: string }
+  reason?: string
+}
+
+export function checkCompatibility(cliVersion: string, kit: KitAssets = KIT): Compatibility {
+  const required = kit.cli
+  if (compareVersions(cliVersion, required.minimum) < 0) {
+    return {
+      compatible: false,
+      cliVersion,
+      required,
+      reason: `this CLI is older than the kit's minimum ${required.minimum}`,
+    }
+  }
+  if (compareVersions(cliVersion, required.maximumExclusive) >= 0) {
+    return {
+      compatible: false,
+      cliVersion,
+      required,
+      reason: `this CLI is at or past the kit's ${required.maximumExclusive} boundary`,
+    }
+  }
+  return { compatible: true, cliVersion, required }
+}
+
+export type SkillHost = 'codex' | 'claudeCode'
+
+export interface DuplicateSource {
+  skill: string
+  host: SkillHost
+  sources: string[]
+}
+
+/** Every `<dir>/<skill>/SKILL.md` under one scope, for the skills this kit ships. */
+function skillsUnder(dir: string): string[] {
+  if (!existsSync(dir)) return []
+  const shipped = new Set(Object.keys(KIT.assets).map((rel) => rel.split('/')[0]!))
+  const found: string[] = []
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    // A project's own skills are not duplicates of anything of ours.
+    if (!shipped.has(entry.name)) continue
+    if (!existsSync(join(dir, entry.name, 'SKILL.md'))) continue
+    found.push(entry.name)
+  }
+  return found
+}
+
+/**
+ * Every installed plugin's `skills` directory under `<home>/.<host>/plugins`.
+ *
+ * Searched rather than constructed. Both hosts currently nest an install as
+ * `plugins/cache/<marketplace>/<plugin>/<version>/skills`, which no hand-written
+ * path guessed correctly — and a diagnostic that silently finds nothing because
+ * a vendor moved a directory is worse than no diagnostic, since it reports
+ * "one source per skill" either way. The depth cap keeps it from walking a
+ * plugin's own contents.
+ */
+function pluginScopes(home: string, host: 'codex' | 'claude'): string[] {
+  const root = join(home, `.${host}`, 'plugins')
+  const out: string[] = []
+
+  const walk = (dir: string, depth: number): void => {
+    if (depth > 5) return
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      // An unreadable directory is not a finding — this is a diagnostic, and
+      // failing it on a permissions quirk would help nobody.
+      return
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      if (entry.name === 'skills') {
+        out.push(join(dir, entry.name))
+        // Do not descend: everything below is one plugin's own skill bodies.
+        continue
+      }
+      walk(join(dir, entry.name), depth + 1)
+    }
+  }
+
+  if (existsSync(root)) walk(root, 0)
+  return out
+}
+
+/**
+ * The same skill reachable twice — WITHIN one host.
+ *
+ * Grouped per host, because `.agents/skills` and `.claude/skills` in one project
+ * are the two required projections rather than a duplication: Codex reads only
+ * the first and Claude Code only the second, and reporting them against each
+ * other would flag every correctly vendored repository.
+ *
+ * The condition that does matter is an installed plugin AND a vendored copy in
+ * the same host. Codex does not merge equal skill names across scopes, so both
+ * appear, and a model choosing between two identical-looking skills is making a
+ * coin flip nobody asked it to make. Claude namespaces plugin skills, but the
+ * recommendation is the same for both hosts so behaviour does not depend on
+ * which one the person happens to be in.
+ *
+ * Evidence-based: it reports the paths it actually found, so a wrong diagnosis
+ * is visible rather than asserted.
+ */
+export function findDuplicateSources(root: string, home = homedir()): DuplicateSource[] {
+  const scopes: Array<[SkillHost, string, string]> = [
+    ['codex', 'vendored', join(root, '.agents', 'skills')],
+    ['codex', 'user skills', join(home, '.agents', 'skills')],
+    ...pluginScopes(home, 'codex').map((dir) => ['codex', 'codex plugin', dir] as [SkillHost, string, string]),
+    ['claudeCode', 'vendored', join(root, '.claude', 'skills')],
+    ...pluginScopes(home, 'claude').map((dir) => ['claudeCode', 'claude plugin', dir] as [SkillHost, string, string]),
+  ]
+
+  const seen = new Map<string, string[]>()
+  // Resolved, because $HOME and the project root can be the same directory
+  // reached by two paths — and a scope counted twice is a duplicate that is not
+  // there.
+  const visited = new Set<string>()
+
+  for (const [host, label, dir] of scopes) {
+    const key = `${host}:${resolvePath(dir)}`
+    if (visited.has(key)) continue
+    visited.add(key)
+    for (const skill of skillsUnder(dir)) {
+      const at = `${host}:${skill}`
+      seen.set(at, [...(seen.get(at) ?? []), `${label}: ${join(dir, skill)}`])
+    }
+  }
+
+  return [...seen.entries()]
+    .filter(([, sources]) => sources.length > 1)
+    .map(([at, sources]) => {
+      const [host, skill] = at.split(':') as [SkillHost, string]
+      return { skill, host, sources }
+    })
+    .sort((a, b) => a.skill.localeCompare(b.skill) || a.host.localeCompare(b.host))
+}

package/src/main.ts

@@ -168,9 +168,21 @@ async function main(): Promise<number> {
 
     // Offline commands scaffold before a credential exists, so resolving one
     // would make `frontera init` impossible on a fresh machine.
+    //
+    // The resolver is given `cwd` — the SAME directory `--dir` already
+    // redirects project discovery to — so a profile selection and an app
+    // project are always read from one place. Two directories would mean
+    // `--dir ../other-customer` could edit one customer's app with another
+    // customer's key.
     const credential = command.meta.offline
       ? { apiUrl: typeof flags['api-url'] === 'string' ? flags['api-url'] : (process.env.FRONTERA_API_URL ?? ''), token: '' }
-      : resolveCredential({ apiUrl: typeof flags['api-url'] === 'string' ? flags['api-url'] : undefined })
+      : await resolveCredential(
+          {
+            apiUrl: typeof flags['api-url'] === 'string' ? flags['api-url'] : undefined,
+            profile: typeof flags.profile === 'string' ? flags.profile : undefined,
+          },
+          { cwd },
+        )
 
     const result = await command.run({
       cwd,

package/src/paths.ts

@@ -0,0 +1,43 @@
+import { createHash } from 'node:crypto'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+export type Env = Record<string, string | undefined>
+
+/**
+ * XDG, not `~/.frontera`.
+ *
+ * The spec assigns credentials to `$XDG_CONFIG_HOME` and disposable data to
+ * `$XDG_CACHE_HOME`; `gh` follows it, and Supabase's `~/.supabase` is its
+ * fallback rather than its design. A bare dotfile directory is the shape
+ * nobody chose deliberately.
+ */
+export function configDir(env: Env = process.env): string {
+  const base = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), '.config')
+  return join(base, 'frontera')
+}
+
+export function configPath(env: Env = process.env): string {
+  return join(configDir(env), 'config.json')
+}
+
+/**
+ * Durable, non-secret data the CLI owns — as distinct from configuration the
+ * user edits and cache anything may delete.
+ *
+ * `frontera setup` materializes an installable plugin here, so a coding host
+ * can be pointed at a real marketplace on a machine with no checkout, no git
+ * remote and no network. Deleting it costs one `frontera setup` re-run, which
+ * is the correct blast radius for data neither secret nor authored.
+ */
+export function dataDir(env: Env = process.env): string {
+  const base = env.XDG_DATA_HOME || join(env.HOME || homedir(), '.local', 'share')
+  return join(base, 'frontera')
+}
+
+/** Disposable, keyed by API origin because the registry is per-deployment. */
+export function cacheDir(apiUrl: string, env: Env = process.env): string {
+  const base = env.XDG_CACHE_HOME || join(env.HOME || homedir(), '.cache')
+  const key = createHash('sha256').update(apiUrl).digest('hex').slice(0, 16)
+  return join(base, 'frontera', key)
+}

package/src/profile-migration.ts

@@ -0,0 +1,101 @@
+import { credentialStore } from './credential-store'
+import { CliError } from './errors'
+import { configPath, type Env } from './paths'
+import {
+  fingerprint,
+  nameFromOrigin,
+  readLegacyConfig,
+  writeProfileConfig,
+  type ProfileConfig,
+  type ProfileMetadata,
+} from './profiles'
+
+export interface MigrationResult {
+  migrated: boolean
+  profiles: Array<{ name: string; apiUrl: string }>
+}
+
+/**
+ * Version 1 → version 2, once, without ever holding the only copy of a key.
+ *
+ * The order matters more than the code does. Every secret is written to the
+ * new profile-addressed store and READ BACK before the legacy config is
+ * rewritten, so a failure at any step leaves the old file intact and the old
+ * credentials recoverable. The alternative — rewrite the metadata first,
+ * migrate the secrets after — turns one bad keychain prompt into a machine
+ * with no working credential and no record of what it used to have.
+ *
+ * Idempotent: a config already at version 2 returns immediately, and a partial
+ * run simply re-copies what it already copied.
+ */
+export async function migrateLegacyConfig(env: Env = process.env): Promise<MigrationResult> {
+  const legacy = readLegacyConfig(env)
+  if (!legacy) return { migrated: false, profiles: [] }
+
+  const origins = Object.entries(legacy.origins ?? {})
+    .filter((entry): entry is [string, { token: string }] => typeof entry[1]?.token === 'string' && entry[1].token.length > 0)
+
+  if (origins.length === 0) {
+    // Nothing recoverable. Still stamp version 2 so the legacy shape stops
+    // being re-read on every command.
+    writeProfileConfig({ schemaVersion: 2, profiles: {} }, env)
+    return { migrated: true, profiles: [] }
+  }
+
+  // The legacy secrets are already plaintext in this very file, so relocating
+  // them into a 0600 store is not a new disclosure — and refusing on a machine
+  // without a keychain would strand the only copy.
+  const store = credentialStore(env, { allowPlaintext: true })
+
+  const taken = new Set<string>()
+  const planned: Array<{ name: string; apiUrl: string; token: string }> = []
+
+  // The previous default becomes `default`, so the first command after
+  // upgrading behaves exactly as it did before.
+  const defaultOrigin = legacy.defaultOrigin
+  if (defaultOrigin && legacy.origins?.[defaultOrigin]?.token) {
+    taken.add('default')
+    planned.push({ name: 'default', apiUrl: defaultOrigin, token: legacy.origins[defaultOrigin]!.token! })
+  }
+
+  for (const [apiUrl, entry] of origins) {
+    if (apiUrl === defaultOrigin && taken.has('default')) continue
+    const name = nameFromOrigin(apiUrl, taken)
+    taken.add(name)
+    planned.push({ name, apiUrl, token: entry.token })
+  }
+
+  const now = new Date().toISOString()
+  const profiles: Record<string, ProfileMetadata> = {}
+
+  for (const { name, apiUrl, token } of planned) {
+    await store.set(name, token)
+    const readBack = await store.get(name)
+    if (readBack !== token) {
+      throw new CliError(`could not verify the migrated key for "${name}"`, {
+        code: 'SECURE_STORE_UNAVAILABLE',
+        hint:
+          `your existing credentials are untouched at ${configPath(env)} — `
+          + 'retry, or set FRONTERA_SECRET_STORE=file and run any command again',
+      })
+    }
+    profiles[name] = {
+      apiUrl,
+      // The legacy file recorded no kind. The prefix is the only evidence, and
+      // `auth verify` refreshes the rest on demand.
+      credentialKind: token.startsWith('sk-org-') ? 'organization' : 'workspace',
+      workspaceId: null,
+      orgId: null,
+      fingerprint: fingerprint(token),
+      createdAt: now,
+      lastVerifiedAt: now,
+    }
+  }
+
+  // Only now: every secret is stored AND verified readable, so dropping the
+  // plaintext tokens cannot lose one.
+  const next: ProfileConfig = { schemaVersion: 2, profiles }
+  writeProfileConfig(next, env)
+
+  return { migrated: true, profiles: planned.map(({ name, apiUrl }) => ({ name, apiUrl })) }
+}