polycast-cli 0.1.0

package/README.md

@@ -0,0 +1,112 @@
+# polycast-cli
+
+The `polycast` CLI is the command-line client for Polycast — OTA
+localization for iOS. It manages projects, languages, and publishing from
+your terminal and CI. Your app's day-to-day string syncing is handled
+automatically by the Xcode build plugin; the CLI is for setup, control,
+and CI.
+
+Requires Node 18+.
+
+```bash
+npx polycast-cli init          # or: npm install -g polycast-cli  →  `polycast`          # or: npm install -g polycast
+```
+
+## Quickstart (60 seconds)
+
+```bash
+npx polycast login                    # paste your org admin token
+npx polycast-cli init          # or: npm install -g polycast-cli  →  `polycast`                     # creates the project, writes polycast.json
+npx polycast langs add ja pt-BR es    # AI drafting starts immediately
+npx polycast publish --wait           # drafts → live bundles
+```
+
+Add the two integration touches `init` printed, build once so the plugin
+pushes your strings, and your app is live in four languages.
+
+## Authentication — two credentials, on purpose
+
+| Credential | Prefix | Used by | Where it lives |
+|---|---|---|---|
+| Org admin token | `pcadm_` | login, init, langs, publish, status | OS keychain (macOS) / `~/.config/polycast/token` 0600 |
+| Project key | `pc_live_` / `pc_test_` | push, pull, build plugin | `polycast.json` in your repo; safe for CI |
+
+The project key can only submit source strings and read published
+translations (which your app ships publicly anyway). The admin token can
+enable languages, edit, and publish — it never goes in files or CI.
+`POLYCAST_ADMIN_TOKEN` / `POLYCAST_PROJECT_KEY` env vars override for
+headless use.
+
+## polycast.json
+
+```json
+{
+  "endpoint": "https://api.polycast.dev",
+  "edgeEndpoint": "https://polycast-edge.mecurylab.workers.dev",
+  "projectKey": "pc_live_8f2k...",
+  "catalogPath": "App/Localizable.xcstrings"
+}
+```
+
+`endpoint` is the write path (ingest/admin — also what the build plugin
+uses); `edgeEndpoint` is the public read path (`pull`, `doctor`). `init`
+writes both and gitignores `.polycast/` (local push state, shared
+byte-for-byte with the Swift build plugin — digests are identical, so the
+CLI and plugin never re-push each other's work).
+
+## Commands
+
+- `login` / `logout` — keychain-stored admin token
+- `init` — detect catalog + Xcode project, create project + key, write
+  config. Idempotent: re-running verifies instead of recreating.
+  Flags: `--name`, `--catalog`, `--endpoint`, `--yes`
+- `langs` — coverage table · `langs add ja ko th` / `langs add all`
+  (App Store locale set) / `langs remove th`. Adding shows the draft
+  count and confirms (auto-yes with `--yes` or `CI=true`).
+- `push` — manual string push (what the plugin does on every build)
+- `pull` — merge **published** translations into the catalog so binary
+  fallbacks stay fresh. `--locales ja,pt-BR` to limit; `--check` exits 1
+  if the catalog is stale (CI guard). Never touches the source language;
+  preserves Xcode's JSON formatting.
+- `publish [locales...]` — promote drafts to live bundles. `--wait`
+  polls until drafting finishes first. Needs-review strings stay
+  unpublished and are called out.
+- `status` — the project at a glance; exit 1 if jobs are dead-lettered
+  (CI health gate). `--json` for scripts.
+- `doctor` — every local + remote check with a one-line fix each:
+  catalog parses · polycast.json valid · build plugin attached ·
+  .polycast gitignored · project key authenticates · admin token valid ·
+  edge reachable · ETag/304 round-trip.
+- `gen` — type-safe Swift constants from the catalog
+  (`--output Sources/Generated/PolycastKeys.swift`); use with
+  `PText(L.paywall.title)`.
+
+All commands: `--json` where output is data, no prompts when `CI=true`
+or `--yes`. Exit codes: 0 success · 1 actionable failure · 2 usage error.
+
+## CI recipes
+
+```yaml
+# bake fresh fallbacks into every release, before xcodebuild archive
+- run: npx polycast pull
+  env:
+    POLYCAST_PROJECT_KEY: ${{ secrets.POLYCAST_PROJECT_KEY }}
+
+# or fail the build if fallbacks are stale
+- run: npx polycast pull --check
+```
+
+Only the project key ever goes in CI secrets; if `polycast.json` is
+committed, no secret is needed at all.
+
+## Troubleshooting
+
+- **No strings after building** → `polycast doctor`; usual cause is the
+  plugin missing from the target or a sandboxed network push
+  (workaround: `polycast push`).
+- **Translations not showing in the app** → drafts aren't live until
+  `polycast publish`; devices refresh on foreground.
+- **A translation looks wrong** → edit via the admin API/dashboard grid
+  (becomes human-locked), publish. Live in minutes.
+- **401** → admin commands need `polycast login`; push/pull need a valid
+  `polycast.json`. Doctor says which.

package/dist/api.d.ts

@@ -0,0 +1,97 @@
+export declare function requireAdminToken(): string;
+export declare const admin: {
+    listProjects: (api: string, token: string) => Promise<{
+        projects: Array<{
+            id: string;
+            name: string;
+            slug: string;
+        }>;
+    }>;
+    resolveKey: (api: string, token: string, key: string) => Promise<{
+        projectId: string;
+        name: string;
+        slug: string;
+    }>;
+    createProject: (api: string, token: string, body: Record<string, unknown>) => Promise<{
+        id: string;
+        name: string;
+        slug: string;
+    }>;
+    createKey: (api: string, token: string, projectId: string, prefix: string) => Promise<{
+        id: string;
+        key: string;
+    }>;
+    putLocales: (api: string, token: string, projectId: string, localesBody: unknown) => Promise<{
+        draftJobsEnqueued: number;
+    }>;
+    status: (api: string, token: string, projectId: string) => Promise<ProjectStatus>;
+    getProject: (api: string, token: string, projectId: string) => Promise<{
+        id: string;
+        name: string;
+        locales: Array<{
+            localeId: string;
+            enabled: boolean;
+            nativeName: string;
+        }>;
+    }>;
+    publish: (api: string, token: string, projectId: string, locales?: string[]) => Promise<{
+        published: Array<{
+            locale: string;
+            bundleVersion: number;
+            etag: string;
+        }>;
+    }>;
+};
+export interface ProjectStatus {
+    project: {
+        id: string;
+        name: string;
+        sourceLocale: string;
+    };
+    totalStrings: number;
+    locales: Array<{
+        locale: string;
+        nativeName: string;
+        enabled: boolean;
+        published: number;
+        drafts: number;
+        needsReview: number;
+        coveragePct: number;
+        lastPublish: {
+            bundleVersion: number;
+            at: string;
+        } | null;
+    }>;
+    deadLetter: Array<{
+        name: string;
+        n: number;
+    }>;
+    eventCount: number;
+}
+export declare const project: {
+    pushStrings: (api: string, key: string, payload: unknown) => Promise<{
+        inserted: number;
+        updated: number;
+        unchanged: number;
+        draftJobsEnqueued: number;
+    }>;
+};
+export declare const edge: {
+    manifest: (edgeUrl: string, key: string) => Promise<{
+        schemaVersion: number;
+        locales: Array<{
+            id: string;
+            nativeName: string;
+            bundleVersion: number;
+        }>;
+    }>;
+    bundle: (edgeUrl: string, key: string, locale: string) => Promise<{
+        bundleVersion: number;
+        strings: Record<string, {
+            v?: string;
+            plural?: Record<string, string>;
+        }>;
+    }>;
+    /** Raw fetch for doctor's ETag round-trip check. */
+    raw: (edgeUrl: string, key: string, locale: string, headers?: Record<string, string>) => Promise<Response>;
+};

package/dist/api.js

@@ -0,0 +1,59 @@
+import { loadToken } from "./keychain.js";
+import { CliError } from "./util.js";
+async function request(url, init = {}) {
+    const headers = {
+        "content-type": "application/json",
+        ...init.headers,
+    };
+    if (init.auth)
+        headers["authorization"] = `Bearer ${init.auth}`;
+    let res;
+    try {
+        res = await fetch(url, { ...init, headers });
+    }
+    catch (err) {
+        throw new CliError(`cannot reach ${new URL(url).origin} — ${err.message}`);
+    }
+    const text = await res.text();
+    let body = null;
+    try {
+        body = text ? JSON.parse(text) : null;
+    }
+    catch { /* non-JSON error page */ }
+    if (!res.ok) {
+        const e = body?.error;
+        if (res.status === 401) {
+            throw new CliError(e?.message ?? "unauthorized — run `polycast login` (admin) or check polycast.json (project key)");
+        }
+        throw new CliError(`${init.method ?? "GET"} ${new URL(url).pathname} → ${res.status}: ${e?.message ?? text.slice(0, 200)}`);
+    }
+    return body;
+}
+export function requireAdminToken() {
+    const token = loadToken();
+    if (!token)
+        throw new CliError("not logged in — run `polycast login`");
+    return token;
+}
+// ---- Admin (org token) ----
+export const admin = {
+    listProjects: (api, token) => request(`${api}/v1/admin/projects`, { auth: token }),
+    resolveKey: (api, token, key) => request(`${api}/v1/admin/projects/resolve-key`, { method: "POST", auth: token, body: JSON.stringify({ key }) }),
+    createProject: (api, token, body) => request(`${api}/v1/admin/projects`, { method: "POST", auth: token, body: JSON.stringify(body) }),
+    createKey: (api, token, projectId, prefix) => request(`${api}/v1/admin/projects/${projectId}/keys`, { method: "POST", auth: token, body: JSON.stringify({ prefix }) }),
+    putLocales: (api, token, projectId, localesBody) => request(`${api}/v1/admin/projects/${projectId}/locales`, { method: "PUT", auth: token, body: JSON.stringify(localesBody) }),
+    status: (api, token, projectId) => request(`${api}/v1/admin/projects/${projectId}/status`, { auth: token }),
+    getProject: (api, token, projectId) => request(`${api}/v1/admin/projects/${projectId}`, { auth: token }),
+    publish: (api, token, projectId, locales) => request(`${api}/v1/admin/projects/${projectId}/publish`, { method: "POST", auth: token, body: JSON.stringify(locales?.length ? { locales } : {}) }),
+};
+// ---- Project key surfaces ----
+export const project = {
+    pushStrings: (api, key, payload) => request(`${api}/v1/projects/${key}/strings`, { method: "POST", auth: key, body: JSON.stringify(payload) }),
+};
+export const edge = {
+    manifest: (edgeUrl, key) => request(`${edgeUrl}/v1/projects/${key}/manifest`),
+    bundle: (edgeUrl, key, locale) => request(`${edgeUrl}/v1/projects/${key}/locales/${locale}`),
+    /** Raw fetch for doctor's ETag round-trip check. */
+    raw: (edgeUrl, key, locale, headers = {}) => fetch(`${edgeUrl}/v1/projects/${key}/locales/${locale}`, { headers }),
+};
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/commands.d.ts

@@ -0,0 +1,27 @@
+export interface Flags {
+    yes: boolean;
+    json: boolean;
+    wait: boolean;
+    check: boolean;
+    token: boolean;
+    name?: string;
+    catalog?: string;
+    endpoint?: string;
+    output?: string;
+    locales?: string;
+    org?: string;
+}
+export declare function login(flags: Flags): Promise<void>;
+export declare function whoami(flags: Flags): Promise<void>;
+export declare function logout(): Promise<void>;
+export declare function init(flags: Flags): Promise<void>;
+export declare function langs(args: string[], flags: Flags): Promise<void>;
+export declare function push(flags: Flags): Promise<void>;
+export declare function pull(flags: Flags): Promise<void>;
+export declare function publish(args: string[], flags: Flags): Promise<void>;
+export declare function status(flags: Flags): Promise<void>;
+export declare function doctor(): Promise<void>;
+/** Plant Polycast+Shadow.swift into each source module so plain Text —
+ * and any design-system component built on it — renders OTA. */
+export declare function shadow(args: string[], _flags: Flags): Promise<void>;
+export declare function gen(flags: Flags): Promise<void>;