polycast-cli 0.2.0 → 0.3.0

package/dist/api.d.ts

@@ -41,7 +41,22 @@ export declare const admin: {
             etag: string;
         }>;
     }>;
+    /** Runtime miss telemetry (newer servers only — callers should treat a
+     * CliError with status 404 as "endpoint not there yet" and hide). */
+    misses: (api: string, token: string, projectId: string, limit?: number) => Promise<{
+        misses: MissRow[];
+    }>;
 };
+export interface MissRow {
+    key: string;
+    locale: string;
+    count: number;
+    fallback: "bundled" | "key";
+    firstSeen: string;
+    lastSeen: string;
+    /** false = the scanner never captured this key — it needs adding. */
+    inCatalog: boolean;
+}
 export interface ProjectStatus {
     project: {
         id: string;

package/dist/api.js

@@ -23,9 +23,9 @@ async function request(url, init = {}) {
     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(e?.message ?? "unauthorized — run `polycast login` (admin) or check polycast.json (project key)", 1, 401);
         }
-        throw new CliError(`${init.method ?? "GET"} ${new URL(url).pathname} → ${res.status}: ${e?.message ?? text.slice(0, 200)}`);
+        throw new CliError(`${init.method ?? "GET"} ${new URL(url).pathname} → ${res.status}: ${e?.message ?? text.slice(0, 200)}`, 1, res.status);
     }
     return body;
 }
@@ -45,6 +45,9 @@ export const admin = {
     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 } : {}) }),
+    /** Runtime miss telemetry (newer servers only — callers should treat a
+     * CliError with status 404 as "endpoint not there yet" and hide). */
+    misses: (api, token, projectId, limit) => request(`${api}/v1/admin/projects/${projectId}/misses${limit !== undefined ? `?limit=${limit}` : ""}`, { auth: token }),
 };
 // ---- Project key surfaces ----
 export const project = {

package/dist/api.js.map

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

package/dist/commands.d.ts

@@ -4,12 +4,15 @@ export interface Flags {
     wait: boolean;
     check: boolean;
     token: boolean;
+    add: boolean;
+    apply: boolean;
     name?: string;
     catalog?: string;
     endpoint?: string;
     output?: string;
     locales?: string;
     org?: string;
+    limit?: string;
 }
 export declare function login(flags: Flags): Promise<void>;
 export declare function whoami(flags: Flags): Promise<void>;
@@ -18,6 +21,13 @@ 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>;
+/** List (dry-run) or delete (--apply) catalog junk: letterless non-
+ * structural artifacts and dangling concatenation fragments ("Save " when
+ * "Save 50%" exists). */
+export declare function prune(flags: Flags): Promise<void>;
+/** Runtime miss telemetry: keys devices requested that the OTA bundle
+ * could not serve (admin endpoint; newer servers only). */
+export declare function misses(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>;

package/dist/commands.js

@@ -6,8 +6,32 @@ import { S, c, g, bold, dim, green, red, yellow, accent, header, section, kv, ba
 import { DEFAULT_API, DEFAULT_EDGE, findConfig, requireConfig, writeConfig, ensureGitignored, stateDir, } from "./config.js";
 import { admin, edge, project, requireAdminToken } from "./api.js";
 import { storeToken, loadToken, clearToken } from "./keychain.js";
-import { parseCatalog, mergeTranslations, writeCatalog, serializeCatalog, addMissingKeys } from "./xcstrings.js";
-import { scanSwiftSources } from "./scan.js";
+import { parseCatalog, mergeTranslations, writeCatalog, serializeCatalog, addMissingKeys, mergeScannerComments, catalogLocales, } from "./xcstrings.js";
+import * as scanner from "./scan.js";
+import { compileDenyKeys, isFileDenied, partitionPush, pruneCandidates, findPbxprojs, findFilesNamed, hasMemberImportVisibility, parseKnownRegions, userFacingInfoPlistKeys, } from "./hygiene.js";
+/** Scan Swift sources, preferring the detailed scanner (feature-detected —
+ * strings + walk stats) and applying polycast.json denyFiles. denyFiles
+ * must apply per-occurrence BEFORE the scanner's cross-file dedupe (which
+ * attributes each key to the first file walked) — a post-hoc filter would
+ * drop keys that also legitimately occur in allowed files. */
+function scanProject(dir, config) {
+    const denyFiles = config.denyFiles ?? [];
+    const fileFilter = denyFiles.length > 0
+        ? (rel) => !isFileDenied(rel, denyFiles)
+        : undefined;
+    if (typeof scanner.scanSwiftSourcesDetailed === "function") {
+        return scanner.scanSwiftSourcesDetailed(dir, {
+            extraCalls: config.scanCalls ?? [],
+            ...(fileFilter !== undefined ? { fileFilter } : {}),
+        });
+    }
+    // Legacy scanner has no fileFilter hook — post-filter is best-effort.
+    const result = { strings: scanner.scanSwiftSources(dir, config.scanCalls ?? []) };
+    if (fileFilter !== undefined) {
+        result.strings = result.strings.filter((s) => fileFilter(s.file));
+    }
+    return result;
+}
 const apiOf = (config) => config?.endpoint ?? DEFAULT_API;
 const edgeOf = (config) => config?.edgeEndpoint ?? DEFAULT_EDGE;
 /** Resolve the project id for admin commands from polycast.json's key. */
@@ -302,31 +326,52 @@ export async function langs(args, flags) {
 export async function push(flags) {
     const { config, dir } = requireConfig();
     const catalogFile = path.resolve(dir, config.catalogPath);
+    const denyKeys = compileDenyKeys(config.denyKeys ?? []); // fail fast on bad config
+    const protectedTerms = new Set(config.protectedTerms ?? []);
     // Zero-config capture: PText / Polycast.string literals in Swift
     // sources are merged into the catalog automatically — write code,
-    // run push, done.
-    const scanned = scanSwiftSources(dir, config.scanCalls ?? []);
+    // run push, done. denyFiles filtering happens inside scanProject.
+    const scanned = scanProject(dir, config).strings;
     {
         const { raw } = parseCatalog(catalogFile);
         const added = addMissingKeys(raw, scanned);
-        if (added.length > 0) {
+        const comments = mergeScannerComments(raw, scanned);
+        if (added.length > 0 || comments.adopted.length > 0)
             writeCatalog(catalogFile, raw);
+        if (added.length > 0) {
             console.log(`\n  ${S.ok}  captured ${bold(String(added.length))} new string(s) from source ${c.muted(`→ ${config.catalogPath}`)}`);
             for (const key of added.slice(0, 8))
                 console.log(`      ${c.positive("+")}  ${c.text(key)}`);
             if (added.length > 8)
                 console.log(`      ${c.muted(`… and ${added.length - 8} more`)}`);
         }
+        if (comments.adopted.length > 0) {
+            console.log(`  ${S.ok}  adopted ${comments.adopted.length} scanner comment(s) into the catalog`);
+        }
+        for (const col of comments.collisions) {
+            console.log(`  ${S.warn}  ${yellow(`comment collision on "${col.key}"`)} ${c.muted(`catalog: "${col.catalog}" ${g.sep} scanned: "${col.scanned}" — catalog wins`)}`);
+        }
     }
     const { sourceLocale, strings } = parseCatalog(catalogFile);
+    const parts = partitionPush(strings, denyKeys, protectedTerms);
     console.log(`\n  ${S.diamond} ${c.text(`${strings.length} strings`)} ${c.muted(`(catalog + source scan) from ${config.catalogPath}`)}`);
+    if (parts.noTranslate > 0) {
+        console.log(`  ${c.muted(`${g.sep} ${parts.noTranslate} excluded (shouldTranslate = false)`)}`);
+    }
+    if (parts.denied.length > 0) {
+        const shown = parts.denied.slice(0, 5).map((k) => JSON.stringify(k)).join(", ");
+        console.log(`  ${c.muted(`${g.sep} ${parts.denied.length} excluded by denyKeys: ${shown}${parts.denied.length > 5 ? ` … and ${parts.denied.length - 5} more` : ""}`)}`);
+    }
+    if (parts.protectedHits.length > 0) {
+        console.log(`  ${S.warn}  ${yellow(`protected term(s) kept verbatim, never pushed: ${parts.protectedHits.map((k) => JSON.stringify(k)).join(", ")}`)}`);
+    }
     const stateFile = path.join(stateDir(dir), "last-push.json");
     const previous = existsSync(stateFile)
         ? (JSON.parse(readFileSync(stateFile, "utf8")).digests ?? {})
         : {};
-    const changedOrNew = strings.filter((s) => previous[s.key] !== s.digest);
+    const changedOrNew = parts.send.filter((s) => previous[s.key] !== s.digest);
     const newCount = changedOrNew.filter((s) => !(s.key in previous)).length;
-    console.log(`  ${green(`+${newCount} new`)} ${S.dot} ${yellow(`~${changedOrNew.length - newCount} changed`)} ${S.dot} ${dim(`${strings.length - changedOrNew.length} unchanged`)}\n`);
+    console.log(`  ${green(`+${newCount} new`)} ${S.dot} ${yellow(`~${changedOrNew.length - newCount} changed`)} ${S.dot} ${dim(`${parts.send.length - changedOrNew.length} unchanged`)}\n`);
     if (changedOrNew.length === 0)
         return;
     const sp = spin("pushing source strings");
@@ -334,13 +379,19 @@ export async function push(flags) {
         schemaVersion: 1,
         projectKey: config.projectKey,
         sourceLocale,
-        strings: changedOrNew.map(({ key, comment, pluralShape, digest }) => ({
-            key, ...(comment !== undefined ? { comment } : {}),
-            ...(pluralShape ? { pluralShape } : {}), digest,
+        strings: changedOrNew.map(({ key, value, comment, pluralShape, structural, digest }) => ({
+            key,
+            ...(value !== undefined ? { value } : {}),
+            ...(comment !== undefined ? { comment } : {}),
+            ...(pluralShape ? { pluralShape } : {}),
+            ...(structural ? { structural: true } : {}),
+            digest,
         })),
     });
     const digests = { ...previous };
-    for (const s of strings)
+    // Record only keys actually eligible for push — un-denying/un-protecting
+    // a key later must make it show up as new, not "unchanged".
+    for (const s of parts.send)
         digests[s.key] = s.digest;
     writeFileSync(stateFile, JSON.stringify({ digests }, null, 2));
     sp.succeed(`pushed — ${accent(String(result.draftJobsEnqueued))} draft job(s) queued across enabled languages`);
@@ -355,10 +406,36 @@ export async function pull(flags) {
     const wanted = flags.locales?.split(",").map((s) => s.trim()).filter(Boolean);
     const locales = manifest.locales.map((l) => l.id)
         .filter((id) => !wanted || wanted.includes(id));
-    let changed = 0;
+    const bundles = new Map();
     for (const locale of locales) {
-        const bundle = await edge.bundle(edgeOf(config), config.projectKey, locale);
-        changed += mergeTranslations(raw, locale, bundle.strings);
+        bundles.set(locale, (await edge.bundle(edgeOf(config), config.projectKey, locale)).strings);
+    }
+    const missing = new Set();
+    let changed = 0;
+    for (const [locale, strings] of bundles) {
+        changed += mergeTranslations(raw, locale, strings, { missing });
+    }
+    // Server keys with no local entry are never dropped silently: report
+    // them, and create them with --add (en value = key; plural skeleton
+    // when any bundle serves plural variants).
+    let addedFromServer = [];
+    if (missing.size > 0 && flags.add && !flags.check) {
+        addedFromServer = [...missing].sort();
+        addMissingKeys(raw, addedFromServer.map((key) => ({
+            key,
+            kind: [...bundles.values()].some((b) => b[key]?.plural) ? "plural" : "simple",
+        })));
+        for (const [locale, strings] of bundles)
+            changed += mergeTranslations(raw, locale, strings);
+    }
+    else if (missing.size > 0) {
+        const first = [...missing].sort().slice(0, 5);
+        console.log(`  ${S.warn}  ${yellow(`${missing.size} server key(s) missing from the local catalog — not merged`)}`);
+        for (const key of first)
+            console.log(`      ${c.muted(g.sep)} ${c.text(JSON.stringify(key))}`);
+        if (missing.size > 5)
+            console.log(`      ${c.muted(`… and ${missing.size - 5} more`)}`);
+        note("run `polycast pull --add` to add them to the catalog (en value = key)");
     }
     const after = serializeCatalog(raw);
     if (flags.check) {
@@ -374,8 +451,97 @@ export async function pull(flags) {
         return;
     }
     writeCatalog(catalogFile, raw);
+    if (addedFromServer.length > 0) {
+        console.log(`  ${S.ok}  added ${bold(String(addedFromServer.length))} server key(s) to the catalog`);
+        for (const key of addedFromServer.slice(0, 5))
+            console.log(`      ${c.positive("+")}  ${c.text(key)}`);
+        if (addedFromServer.length > 5)
+            console.log(`      ${c.muted(`… and ${addedFromServer.length - 5} more`)}`);
+    }
     success(`merged ${locales.map(flag).join(" ")}  ${locales.join(", ")} — ${changed} value(s) updated`);
 }
+// ---- prune ----
+/** List (dry-run) or delete (--apply) catalog junk: letterless non-
+ * structural artifacts and dangling concatenation fragments ("Save " when
+ * "Save 50%" exists). */
+export async function prune(flags) {
+    const { config, dir } = requireConfig();
+    const catalogFile = path.resolve(dir, config.catalogPath);
+    const { raw } = parseCatalog(catalogFile);
+    const { artifacts, fragments } = pruneCandidates(Object.keys(raw.strings));
+    const all = [...artifacts, ...fragments];
+    if (!flags.json) {
+        if (all.length === 0) {
+            success("catalog is clean — nothing to prune");
+        }
+        else {
+            header("prune", `${all.length} candidate(s) in ${config.catalogPath}`);
+            for (const key of artifacts) {
+                console.log(`  ${c.negative("−")} ${c.text(JSON.stringify(key))}  ${c.muted("empty/letterless artifact")}`);
+            }
+            for (const key of fragments) {
+                console.log(`  ${c.negative("−")} ${c.text(JSON.stringify(key))}  ${c.muted("dangling concatenation fragment (strict prefix of another key)")}`);
+            }
+        }
+    }
+    // Delete BEFORE reporting: `applied` in the machine output must reflect
+    // a write that actually happened, not one that was about to.
+    const applied = flags.apply && all.length > 0;
+    if (applied) {
+        for (const key of all)
+            delete raw.strings[key];
+        writeCatalog(catalogFile, raw);
+    }
+    if (flags.json) {
+        console.log(JSON.stringify({ artifacts, fragments, applied }, null, 2));
+        return;
+    }
+    if (all.length === 0)
+        return;
+    if (!flags.apply) {
+        console.log();
+        note("dry run — re-run with --apply to delete these from the catalog");
+        console.log();
+        return;
+    }
+    success(`pruned ${all.length} key(s) from ${config.catalogPath}`);
+}
+// ---- misses ----
+/** Runtime miss telemetry: keys devices requested that the OTA bundle
+ * could not serve (admin endpoint; newer servers only). */
+export async function misses(flags) {
+    const { config, token, projectId } = await resolveProject();
+    let limit = 100;
+    if (flags.limit !== undefined) {
+        limit = Number(flags.limit);
+        if (!Number.isInteger(limit) || limit < 1)
+            throw new CliError("--limit must be a positive integer", 2);
+    }
+    const { misses: rows } = await admin.misses(apiOf(config), token, projectId, limit);
+    if (flags.json) {
+        console.log(JSON.stringify(rows, null, 2));
+        return;
+    }
+    if (rows.length === 0) {
+        success("no runtime misses reported");
+        return;
+    }
+    const sorted = [...rows].sort((a, b) => b.count - a.count);
+    header("runtime misses", `${rows.length} key/locale pair(s) the SDK could not serve OTA`);
+    console.log(table(["key", "locale", "count", "fallback", "last seen"], sorted.map((r) => [
+        c.text(r.key) + (r.inCatalog ? "" : ` ${c.danger("(uncaptured)")}`),
+        c.accent2(r.locale),
+        String(r.count),
+        c.muted(r.fallback),
+        c.muted(relativeTime(r.lastSeen)),
+    ])));
+    const uncaptured = sorted.filter((r) => !r.inCatalog).length;
+    console.log();
+    if (uncaptured > 0) {
+        note(`${uncaptured} uncaptured key(s) — the scanner never saw them; check scanCalls in polycast.json or add them to the catalog`);
+        console.log();
+    }
+}
 // ---- publish ----
 export async function publish(args, flags) {
     const { config, token, projectId } = await resolveProject();
@@ -447,6 +613,22 @@ export async function status(flags) {
             ? `${c.text(`bundle v${latest.bundleVersion}`)} ${c.positive("live")} ${c.muted(`${g.sep} published ${relativeTime(latest.at)}`)}`
             : c.muted("nothing published yet"));
         kv("jobs", failed > 0 ? c.negative(`${failed} failed — inspect with status --json`) : c.positive("all healthy"));
+        // Runtime misses (newer servers only — a 404 means the endpoint does
+        // not exist yet; hide the line so old servers keep working).
+        try {
+            const { misses: missRows } = await admin.misses(apiOf(config), token, projectId, 500);
+            if (missRows.length > 0) {
+                const total = missRows.reduce((a, r) => a + r.count, 0);
+                const uncaptured = missRows.filter((r) => !r.inCatalog).length;
+                kv("runtime misses", c.danger(`${total} across ${missRows.length} key/locale pair(s)`)
+                    + (uncaptured > 0 ? c.muted(` ${g.sep} ${uncaptured} uncaptured`) : "")
+                    + c.muted(` ${g.sep} see \`polycast misses\``));
+            }
+        }
+        catch {
+            // Telemetry is informational — a transient 5xx/timeout must never
+            // take down `status`. Only `polycast misses` hard-fails.
+        }
         section("languages");
         console.log(table(["", "locale", "coverage", "", "drafts", "review", "bundle"], enabled.map((l) => [
             flag(l.locale),
@@ -482,6 +664,7 @@ export async function doctor() {
     await check("polycast.json present and valid", () => {
         if (!found)
             throw new Error("run `polycast init`");
+        compileDenyKeys(found.config.denyKeys ?? []); // invalid regex = invalid config
         return found.config.projectKey.slice(0, 12) + "…";
     });
     if (!found) {
@@ -540,6 +723,102 @@ export async function doctor() {
         if (cached.status !== 304)
             throw new Error(`expected 304, got ${cached.status}`);
     });
+    // ---- warn-only hygiene (informational; never fails doctor) ----
+    const warnOnly = async (label, fn) => {
+        const sp = spin(label);
+        try {
+            const r = await fn();
+            const warnings = r.warnings ?? [];
+            if (warnings.length === 0) {
+                sp.succeed(`${label}${r.detail ? dim(`  ${r.detail}`) : ""}`);
+                return;
+            }
+            sp.warn(`${label}${r.detail ? dim(`  ${r.detail}`) : ""}`);
+            for (const w of warnings)
+                console.log(`      ${S.warn} ${yellow(w)}`);
+        }
+        catch (err) {
+            sp.warn(`${label} ${dim(`— skipped (${err.message})`)}`);
+        }
+    };
+    const rel = (f) => path.relative(dir, f) || ".";
+    const pbxprojs = findPbxprojs(dir);
+    await warnOnly("source scan", () => {
+        const r = scanProject(dir, config);
+        if (!r.stats)
+            return { detail: `${r.strings.length} string(s)` };
+        const skipped = r.stats.dirsSkipped.length > 0
+            ? ` (${r.stats.dirsSkipped.slice(0, 4).map(rel).join(", ")}${r.stats.dirsSkipped.length > 4 ? ", …" : ""})`
+            : "";
+        return { detail: `${r.strings.length} string(s) ${g.sep} ${r.stats.filesScanned} file(s) scanned ${g.sep} ${r.stats.dirsSkipped.length} dir(s) skipped${skipped}` };
+    });
+    await warnOnly("member import visibility", () => {
+        if (pbxprojs.length === 0)
+            return { detail: "no .pbxproj — skipped" };
+        const bad = pbxprojs.filter((f) => hasMemberImportVisibility(readFileSync(f, "utf8")));
+        return {
+            warnings: bad.map((f) => `${rel(f)}: SWIFT_UPCOMING_FEATURE_MEMBER_IMPORT_VISIBILITY = YES breaks the Text shadow — set it to NO`),
+        };
+    });
+    await warnOnly("Text shadow coverage", () => {
+        const roots = detectModuleRoots(dir);
+        const missing = roots.filter((r) => !existsSync(path.join(r, "Polycast+Shadow.swift")));
+        return {
+            detail: `${roots.length - missing.length}/${roots.length} module(s) shadowed`,
+            warnings: missing.map((r) => `module ${rel(r)} has no Polycast+Shadow.swift — plain Text stays bundled-only there (run \`polycast shadow\`)`),
+        };
+    });
+    await warnOnly("Info.plist localization", () => {
+        const sources = [...findFilesNamed(dir, (n) => n === "Info.plist"), ...pbxprojs];
+        const keys = new Set();
+        for (const f of sources) {
+            for (const k of userFacingInfoPlistKeys(readFileSync(f, "utf8")))
+                keys.add(k);
+        }
+        if (keys.size === 0)
+            return { detail: "no user-facing Info.plist keys" };
+        if (findFilesNamed(dir, (n) => n === "InfoPlist.xcstrings").length > 0) {
+            return { detail: `${keys.size} user-facing key(s), InfoPlist.xcstrings present` };
+        }
+        return {
+            warnings: [`user-facing Info.plist key(s) without an InfoPlist.xcstrings — permission prompts stay unlocalized: ${[...keys].sort().join(", ")}`],
+        };
+    });
+    await warnOnly("Xcode knownRegions", () => {
+        if (pbxprojs.length === 0)
+            return { detail: "no .pbxproj — skipped" };
+        const { raw } = parseCatalog(path.resolve(dir, config.catalogPath));
+        const locales = catalogLocales(raw).filter((l) => l !== raw.sourceLanguage);
+        if (locales.length === 0)
+            return { detail: "no translated locales in the catalog yet" };
+        const warnings = [];
+        for (const f of pbxprojs) {
+            const regions = new Set(parseKnownRegions(readFileSync(f, "utf8")));
+            if (regions.size === 0)
+                continue;
+            const missing = locales.filter((l) => !regions.has(l));
+            if (missing.length > 0) {
+                warnings.push(`${rel(f)}: knownRegions missing ${missing.join(", ")} — add them in Xcode (Project → Info → Localizations)`);
+            }
+        }
+        return { detail: warnings.length === 0 ? `${locales.length} catalog locale(s) covered` : undefined, warnings };
+    });
+    await warnOnly("pull currency", async () => {
+        const manifest = await edge.manifest(edgeOf(config), config.projectKey);
+        if (manifest.locales.length === 0)
+            return { detail: "no published bundles yet" };
+        const { raw } = parseCatalog(path.resolve(dir, config.catalogPath));
+        const stale = [];
+        for (const l of manifest.locales) {
+            const bundle = await edge.bundle(edgeOf(config), config.projectKey, l.id);
+            const clone = structuredClone(raw);
+            if (mergeTranslations(clone, l.id, bundle.strings) > 0)
+                stale.push(l.id);
+        }
+        if (stale.length === 0)
+            return { detail: `catalog current with ${manifest.locales.length} published locale(s)` };
+        return { warnings: [`catalog fallbacks stale for ${stale.join(", ")} — run \`polycast pull\``] };
+    });
     if (failures > 0) {
         console.log(`\n  ${S.fail} ${red(`${failures} check(s) failed`)}\n`);
         process.exit(1);