@athsra/cli 0.1.0 → 1.0.0

package/src/lib/secrets-manifest.ts

@@ -0,0 +1,309 @@
+/**
+ * secrets-manifest.ts — sibling worker 가 athsra envelope 에서 sync 할 키를 명시.
+ *
+ * **Option γ (default-deny + opt-in)** — Phase 2.6 (2026-05-26):
+ * envelope 의 모든 키를 무차별 sync 하지 않고, manifest 에 명시된 키만 sync.
+ * Hub-not-enforcer 정합 — athsra 가 강제하지 않고, sibling owner 가 명시적으로
+ * opt-in. secret leak 사고를 최소 권한 원칙으로 줄임.
+ *
+ * Default 위치: `<worker.cwd>/.athsra/secrets.json`
+ *
+ * Schema v1:
+ * ```json
+ * {
+ *   "$schema": "https://athsra.com/schema/secrets-manifest-v1.json",
+ *   "version": "1",
+ *   "secrets": ["DATABASE_URL", "SESSION_SECRET", ...]
+ * }
+ * ```
+ *
+ * 정공법:
+ *  - 의존성 추가 회피 (Zod X) — manual validation
+ *  - error message 가 곧 onboarding 가이드 (`athsra manifest init` 안내)
+ *  - alphabetical sort + atomic write — diff-friendly
+ *  - host repo biome.json 자동 감지 — sibling 의 indent (tab/space N) 정합
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const MANIFEST_DIR = '.athsra';
+export const MANIFEST_FILE = 'secrets.json';
+export const MANIFEST_SCHEMA_VERSION = '1';
+export const MANIFEST_SCHEMA_URL = 'https://athsra.com/schema/secrets-manifest-v1.json';
+
+const IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export interface SecretsManifest {
+  /** JSON Schema URL (informational, editor LSP 용) */
+  $schema?: string;
+  /** Schema version. 현재 v1 만 지원. */
+  version: '1';
+  /** envelope 에서 worker 로 sync 할 secret key 목록. alphabetical. */
+  secrets: string[];
+}
+
+export interface LoadOptions {
+  /** Worker 의 wrangler.jsonc 가 있는 디렉토리. manifest 는 이 안의 .athsra/secrets.json */
+  workerCwd: string;
+}
+
+export interface LoadResult {
+  /** 파일이 발견되고 valid 인 경우 manifest, 아니면 null */
+  manifest: SecretsManifest | null;
+  /** Absolute manifest path (존재 여부 무관) */
+  path: string;
+  /** 파일이 존재하면 true */
+  exists: boolean;
+  /** 존재하나 invalid 인 경우 사람 가독 에러 (없으면 undefined) */
+  error?: string;
+}
+
+export function manifestPath(workerCwd: string): string {
+  return join(workerCwd, MANIFEST_DIR, MANIFEST_FILE);
+}
+
+/**
+ * Validate parsed manifest object.
+ *
+ * @returns 첫 번째 실패 사유 (string) 또는 valid 시 null
+ */
+function validateManifest(obj: unknown): string | null {
+  if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
+    return 'manifest root must be a JSON object';
+  }
+  const m = obj as Record<string, unknown>;
+  if (m.version !== MANIFEST_SCHEMA_VERSION) {
+    return `unsupported version '${String(m.version)}' (expected '${MANIFEST_SCHEMA_VERSION}')`;
+  }
+  if (!Array.isArray(m.secrets)) {
+    return 'field "secrets" must be a string array';
+  }
+  const seen = new Set<string>();
+  for (let i = 0; i < m.secrets.length; i++) {
+    const k = m.secrets[i];
+    if (typeof k !== 'string') {
+      return `secrets[${i}] is not a string`;
+    }
+    if (k.length === 0) {
+      return `secrets[${i}] is empty`;
+    }
+    if (!IDENTIFIER_PATTERN.test(k)) {
+      return `secrets[${i}] '${k}' is not a valid env var identifier (^[A-Za-z_][A-Za-z0-9_]*$)`;
+    }
+    if (seen.has(k)) {
+      return `secrets[${i}] '${k}' is duplicated`;
+    }
+    seen.add(k);
+  }
+  if (m.$schema !== undefined && typeof m.$schema !== 'string') {
+    return 'field "$schema" must be a string when present';
+  }
+  return null;
+}
+
+export function loadManifest(opts: LoadOptions): LoadResult {
+  const path = manifestPath(opts.workerCwd);
+  if (!existsSync(path)) {
+    return { manifest: null, path, exists: false };
+  }
+  let text: string;
+  try {
+    text = readFileSync(path, 'utf-8');
+  } catch (err) {
+    return {
+      manifest: null,
+      path,
+      exists: true,
+      error: `read failed: ${(err as Error).message}`,
+    };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    return {
+      manifest: null,
+      path,
+      exists: true,
+      error: `JSON parse failed: ${(err as Error).message}`,
+    };
+  }
+  const validationError = validateManifest(parsed);
+  if (validationError) {
+    return { manifest: null, path, exists: true, error: validationError };
+  }
+  const m = parsed as SecretsManifest;
+  return {
+    manifest: { $schema: m.$schema, version: m.version, secrets: [...m.secrets].sort() },
+    path,
+    exists: true,
+  };
+}
+
+/**
+ * envelope 의 key set 에 대해 manifest 적용 결과.
+ *
+ * - `allowed` — envelope ∩ manifest.secrets (실제 sync 대상)
+ * - `missing` — manifest 에 있으나 envelope 에 없는 키 (사용자에게 warning)
+ * - `excluded` — envelope 에 있으나 manifest 에 없는 키 (sync 제외 됨, 정보)
+ */
+export interface ApplyResult {
+  allowed: string[];
+  missing: string[];
+  excluded: string[];
+}
+
+export function applyManifest(
+  manifest: SecretsManifest,
+  envelopeKeys: string[],
+): ApplyResult {
+  const envSet = new Set(envelopeKeys);
+  const manSet = new Set(manifest.secrets);
+  const allowed: string[] = [];
+  const missing: string[] = [];
+  for (const k of manifest.secrets) {
+    if (envSet.has(k)) allowed.push(k);
+    else missing.push(k);
+  }
+  const excluded: string[] = [];
+  for (const k of envelopeKeys) {
+    if (!manSet.has(k)) excluded.push(k);
+  }
+  return {
+    allowed: allowed.sort(),
+    missing: missing.sort(),
+    excluded: excluded.sort(),
+  };
+}
+
+/**
+ * 새 manifest 객체 생성 — secrets 자동 sort + dedup + 검증.
+ *
+ * @throws Error 검증 실패 시
+ */
+export function createManifest(secrets: string[]): SecretsManifest {
+  const deduped = Array.from(new Set(secrets)).sort();
+  const m: SecretsManifest = {
+    $schema: MANIFEST_SCHEMA_URL,
+    version: MANIFEST_SCHEMA_VERSION,
+    secrets: deduped,
+  };
+  const err = validateManifest(m);
+  if (err) {
+    throw new Error(`invalid manifest: ${err}`);
+  }
+  return m;
+}
+
+interface HostBiomeConfig {
+  /** biome.json 파일이 ancestor 에서 발견됐는지 */
+  hasFile: boolean;
+  /** formatter 객체 (biome.json 안에 있을 때만, 파싱 실패 또는 미설정 시 null) */
+  formatter: { indentStyle?: string; indentWidth?: number } | null;
+}
+
+/**
+ * Host repo 의 biome.json (parent 디렉토리 traversal) 검색.
+ * sibling repo 별로 indentStyle 이 다를 수 있어 (modfolio-connect=tab, athsra/ecosystem=space)
+ * manifest 작성 시 호스트 정합 indent 적용 위함.
+ *
+ * @returns `hasFile` 로 biome.json 존재 여부 + `formatter` 내용.
+ *          존재 안 함 vs 존재하지만 formatter 누락 구분 (biome 기본값 적용 정합).
+ *          탐색 깊이는 안전을 위해 10 단계 제한.
+ */
+function findHostBiomeFormatter(workerCwd: string): HostBiomeConfig {
+  const MAX_PARENT_LOOKUP = 10;
+  let dir = workerCwd;
+  for (let i = 0; i < MAX_PARENT_LOOKUP; i++) {
+    const biomePath = join(dir, 'biome.json');
+    if (existsSync(biomePath)) {
+      try {
+        const cfg = JSON.parse(readFileSync(biomePath, 'utf-8')) as {
+          formatter?: { indentStyle?: string; indentWidth?: number };
+        };
+        return { hasFile: true, formatter: cfg.formatter ?? null };
+      } catch {
+        // malformed JSON → 안전 fallback 으로 not-found 처리 (RFC 표준 2-space 적용)
+        return { hasFile: false, formatter: null };
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return { hasFile: false, formatter: null };
+    dir = parent;
+  }
+  return { hasFile: false, formatter: null };
+}
+
+/**
+ * Host repo 의 biome.json 에서 JSON 작성 indent 추론.
+ *
+ * - `indentStyle=tab` → `'\t'`
+ * - `indentStyle=space` → `indentWidth` (default 2)
+ * - biome.json 발견되었으나 formatter 미설정 → `'\t'` (biome 기본값)
+ * - biome.json 없음 → `2` (RFC 표준 가독값)
+ */
+export function detectManifestIndent(workerCwd: string): string | number {
+  const { hasFile, formatter } = findHostBiomeFormatter(workerCwd);
+  if (!hasFile) return 2;
+  if (!formatter) return '\t';
+  if (formatter.indentStyle === 'tab') return '\t';
+  if (formatter.indentStyle === 'space') return formatter.indentWidth ?? 2;
+  return '\t';
+}
+
+/**
+ * Atomic write — temp file → rename. mkdir -p `.athsra/` if missing.
+ * Host repo biome.json indent 정합 (modfolio-connect tab / athsra·ecosystem 2-space 등).
+ *
+ * @returns 작성된 absolute path
+ */
+export function saveManifest(workerCwd: string, manifest: SecretsManifest): string {
+  const err = validateManifest(manifest);
+  if (err) {
+    throw new Error(`refuse to save invalid manifest: ${err}`);
+  }
+  const target = manifestPath(workerCwd);
+  const dir = dirname(target);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  const sorted: SecretsManifest = {
+    $schema: manifest.$schema ?? MANIFEST_SCHEMA_URL,
+    version: manifest.version,
+    secrets: [...manifest.secrets].sort(),
+  };
+  const indent = detectManifestIndent(workerCwd);
+  const text = `${JSON.stringify(sorted, null, indent)}\n`;
+  const tmp = `${target}.tmp`;
+  writeFileSync(tmp, text, { encoding: 'utf-8' });
+  renameSync(tmp, target);
+  return target;
+}
+
+/** Human-friendly error explaining how to fix a missing manifest. */
+export function describeMissingManifest(workerCwd: string, workerName: string): string {
+  const path = manifestPath(workerCwd);
+  return [
+    `✗ secrets manifest not found: ${path}`,
+    '',
+    'athsra Phase 2.6 (Option γ, 2026-05-26+) 는 default-deny + opt-in 입니다.',
+    'envelope 의 모든 키를 무차별 sync 하지 않으려면 manifest 가 필요합니다.',
+    '',
+    '해결:',
+    `  1) 자동 생성 (envelope 의 모든 키를 기본 manifest 로):`,
+    `     cd ${workerCwd}`,
+    `     athsra manifest init --worker=${workerName} --all`,
+    '',
+    `  2) 명시적 키만 (권장, 최소 권한):`,
+    `     athsra manifest init --worker=${workerName} --keys=KEY1,KEY2,...`,
+    '',
+    '  3) 일회성 우회 (legacy, 권장 X):',
+    '     athsra adopt --allow-all',
+    '     bun scripts/sync-wrangler-secrets.ts ... --allow-all',
+    '',
+    'docs: knowledge/canon/secret-store.md § Manifest opt-in (γ)',
+  ].join('\n');
+}
+
+/** test helpers */
+export const __test = { validateManifest, findHostBiomeFormatter };

package/src/lib/workers-builds.ts

@@ -0,0 +1,274 @@
+/**
+ * workers-builds.ts — Cloudflare Workers Builds API client (idempotent).
+ *
+ * canon: modfolio-ecosystem/knowledge/canon/cf-workers-builds-api.md
+ *
+ * 모든 함수는 `accountId` + `apiToken` 을 명시 받아 호출 — athsra envelope 또는
+ * env 변수 출처와 분리. 호출자 (commands/adopt, scripts/setup-workers-builds) 가
+ * token 출처 결정.
+ *
+ * 정공법: idempotent — 같은 인자로 재호출 시 안전 (PUT/PATCH 또는 GET 후 분기).
+ */
+
+const CF_BASE = 'https://api.cloudflare.com/client/v4';
+
+export interface CfResult<T> {
+  ok: boolean;
+  status: number;
+  result: T | null;
+  errors: { code?: number; message?: string }[];
+}
+
+export interface WorkerService {
+  default_environment: { script_tag: string };
+}
+
+export interface RepoConnection {
+  repo_connection_uuid: string;
+  repo_id: string;
+  repo_name: string;
+  provider_account_name: string;
+}
+
+export interface BuildToken {
+  build_token_uuid: string;
+  build_token_name: string;
+  owner_type: string;
+}
+
+export interface Trigger {
+  trigger_uuid: string;
+  trigger_name: string;
+  root_directory: string;
+  build_command: string;
+  deploy_command: string;
+  branch_includes: string[];
+  build_token_name?: string;
+  build_token_uuid?: string;
+  repo_connection_uuid?: string | null;
+}
+
+export interface Build {
+  build_uuid: string;
+  status: string;
+  build_outcome: string | null;
+  created_on: string;
+}
+
+export interface TriggerSpec {
+  externalScriptId: string;
+  repoConnectionUuid: string;
+  buildTokenUuid: string;
+  triggerName: string;
+  buildCommand: string;
+  deployCommand: string;
+  rootDirectory: string;
+  branchIncludes: string[];
+  branchExcludes?: string[];
+  pathIncludes?: string[];
+  pathExcludes?: string[];
+}
+
+async function cfApi<T>(
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+  path: string,
+  apiToken: string,
+  body?: unknown,
+): Promise<CfResult<T>> {
+  const res = await fetch(`${CF_BASE}${path}`, {
+    method,
+    headers: {
+      Authorization: `Bearer ${apiToken}`,
+      ...(body ? { 'content-type': 'application/json' } : {}),
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const json = (await res.json().catch(() => ({}))) as {
+    success?: boolean;
+    result?: T;
+    errors?: { code?: number; message?: string }[];
+  };
+  return {
+    ok: json.success === true,
+    status: res.status,
+    result: json.result ?? null,
+    errors: json.errors ?? [],
+  };
+}
+
+/** Worker 의 script_tag (32-hex) 가져오기. Worker 미존재 시 null. */
+export async function getWorkerTag(
+  accountId: string,
+  apiToken: string,
+  workerName: string,
+): Promise<string | null> {
+  const res = await cfApi<WorkerService>(
+    'GET',
+    `/accounts/${accountId}/workers/services/${workerName}`,
+    apiToken,
+  );
+  if (!res.ok || !res.result) return null;
+  return res.result.default_environment.script_tag;
+}
+
+/** Repo connection 보장 (idempotent PUT). */
+export async function ensureRepoConnection(
+  accountId: string,
+  apiToken: string,
+  spec: {
+    providerType?: 'github';
+    providerAccountId: string;
+    providerAccountName: string;
+    repoId: string;
+    repoName: string;
+  },
+): Promise<RepoConnection> {
+  const res = await cfApi<RepoConnection>(
+    'PUT',
+    `/accounts/${accountId}/builds/repos/connections`,
+    apiToken,
+    {
+      provider_type: spec.providerType ?? 'github',
+      provider_account_id: spec.providerAccountId,
+      provider_account_name: spec.providerAccountName,
+      repo_id: spec.repoId,
+      repo_name: spec.repoName,
+    },
+  );
+  if (!res.ok || !res.result) {
+    const detail = res.errors.map((e) => e.message).join('; ') || `status ${res.status}`;
+    throw new Error(`repo connection failed: ${detail}`);
+  }
+  return res.result;
+}
+
+/** 가장 최근 build token (목록의 [0]). */
+export async function getLatestBuildToken(
+  accountId: string,
+  apiToken: string,
+): Promise<BuildToken> {
+  const res = await cfApi<BuildToken[]>('GET', `/accounts/${accountId}/builds/tokens`, apiToken);
+  const first = res.result?.[0];
+  if (!res.ok || !first) {
+    throw new Error('no build tokens — CF Dashboard 에서 1회 발급 필요');
+  }
+  return first;
+}
+
+/** Worker 의 기존 trigger 목록. */
+export async function listTriggers(
+  accountId: string,
+  apiToken: string,
+  workerTag: string,
+): Promise<Trigger[]> {
+  const res = await cfApi<Trigger[]>(
+    'GET',
+    `/accounts/${accountId}/builds/workers/${workerTag}/triggers`,
+    apiToken,
+  );
+  return res.result ?? [];
+}
+
+/** Trigger 생성 또는 갱신 (root + branch 매칭으로 멱등성). */
+export async function upsertTrigger(
+  accountId: string,
+  apiToken: string,
+  spec: TriggerSpec,
+): Promise<{ trigger: Trigger; created: boolean }> {
+  const body = {
+    external_script_id: spec.externalScriptId,
+    repo_connection_uuid: spec.repoConnectionUuid,
+    build_token_uuid: spec.buildTokenUuid,
+    trigger_name: spec.triggerName,
+    build_command: spec.buildCommand,
+    deploy_command: spec.deployCommand,
+    root_directory: spec.rootDirectory,
+    branch_includes: spec.branchIncludes,
+    branch_excludes: spec.branchExcludes ?? [],
+    path_includes: spec.pathIncludes ?? ['*'],
+    path_excludes: spec.pathExcludes ?? [],
+  };
+  const existing = await listTriggers(accountId, apiToken, spec.externalScriptId);
+  const matched = existing.find(
+    (t) =>
+      t.root_directory === spec.rootDirectory &&
+      t.branch_includes?.some((b) => spec.branchIncludes.includes(b)),
+  );
+  if (matched) {
+    const patched = await cfApi<Trigger>(
+      'PATCH',
+      `/accounts/${accountId}/builds/triggers/${matched.trigger_uuid}`,
+      apiToken,
+      body,
+    );
+    if (!patched.ok || !patched.result) {
+      const detail = patched.errors.map((e) => e.message).join('; ') || `status ${patched.status}`;
+      throw new Error(`trigger PATCH failed: ${detail}`);
+    }
+    return { trigger: patched.result, created: false };
+  }
+  const created = await cfApi<Trigger>(
+    'POST',
+    `/accounts/${accountId}/builds/triggers`,
+    apiToken,
+    body,
+  );
+  if (!created.ok || !created.result) {
+    const detail = created.errors.map((e) => e.message).join('; ') || `status ${created.status}`;
+    throw new Error(`trigger create failed: ${detail}`);
+  }
+  return { trigger: created.result, created: true };
+}
+
+/** Trigger 의 env vars (PATCH = upsert). */
+export async function setTriggerEnvVars(
+  accountId: string,
+  apiToken: string,
+  triggerUuid: string,
+  envVars: Record<string, { value: string; is_secret: boolean }>,
+): Promise<void> {
+  const res = await cfApi(
+    'PATCH',
+    `/accounts/${accountId}/builds/triggers/${triggerUuid}/environment_variables`,
+    apiToken,
+    envVars,
+  );
+  if (!res.ok) {
+    const detail = res.errors.map((e) => e.message).join('; ') || `status ${res.status}`;
+    throw new Error(`env vars PATCH failed: ${detail}`);
+  }
+}
+
+/** Manual build 트리거 (body = {"branch":"<name>"} 필수). */
+export async function triggerManualBuild(
+  accountId: string,
+  apiToken: string,
+  triggerUuid: string,
+  branch: string,
+): Promise<Build> {
+  const res = await cfApi<Build>(
+    'POST',
+    `/accounts/${accountId}/builds/triggers/${triggerUuid}/builds`,
+    apiToken,
+    { branch },
+  );
+  if (!res.ok || !res.result) {
+    const detail = res.errors.map((e) => e.message).join('; ') || `status ${res.status}`;
+    throw new Error(`manual build failed: ${detail}`);
+  }
+  return res.result;
+}
+
+/** Build 상태 조회. */
+export async function getBuild(
+  accountId: string,
+  apiToken: string,
+  buildUuid: string,
+): Promise<Build | null> {
+  const res = await cfApi<Build>(
+    'GET',
+    `/accounts/${accountId}/builds/builds/${buildUuid}`,
+    apiToken,
+  );
+  return res.result;
+}