polycast-cli 0.1.0 → 0.3.0

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. */
@@ -117,6 +141,41 @@ function detectCatalog(cwd) {
     }
     return null;
 }
+/** Directory holding the most Swift sources — where the catalog belongs. */
+function bestSourceDir(cwd) {
+    const counts = new Map();
+    const walk = (d, depth) => {
+        if (depth > 4)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(d);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            if (name.startsWith(".") || ["node_modules", "Pods", "build", "DerivedData", ".build"].includes(name) || name.endsWith(".xcodeproj"))
+                continue;
+            const full = path.join(d, name);
+            try {
+                if (statSync(full).isDirectory())
+                    walk(full, depth + 1);
+                else if (name.endsWith(".swift"))
+                    counts.set(d, (counts.get(d) ?? 0) + 1);
+            }
+            catch { /* skip */ }
+        }
+    };
+    walk(cwd, 0);
+    let best = cwd, bestCount = 0;
+    for (const [dir, n] of counts)
+        if (n > bestCount) {
+            best = dir;
+            bestCount = n;
+        }
+    return best;
+}
 function detectProjectName(cwd) {
     const xcodeproj = readdirSync(cwd).find((f) => f.endsWith(".xcodeproj"));
     if (xcodeproj)
@@ -147,9 +206,16 @@ export async function init(flags) {
         return;
     }
     const token = requireAdminToken();
-    const catalogPath = flags.catalog ?? detectCatalog(cwd);
+    let catalogPath = flags.catalog ?? detectCatalog(cwd);
     if (!catalogPath) {
-        throw new CliError("could not find a unique .xcstrings catalog — pass --catalog <path>", 2);
+        // No String Catalog yet (apps that never localized don't have one) —
+        // create it. The source scanner fills it from Text("…") literals on
+        // the first push, so empty is the correct starting state.
+        const appDir = bestSourceDir(cwd);
+        catalogPath = path.relative(cwd, path.join(appDir, "Localizable.xcstrings"));
+        writeFileSync(path.join(appDir, "Localizable.xcstrings"), JSON.stringify({ sourceLanguage: "en", strings: {}, version: "1.0" }, null, 2) + "\n");
+        console.log(`  ${S.ok}  created ${catalogPath} ${c.muted("(none existed — the source scanner fills it on push)")}`);
+        console.log(`  ${S.warn}  ${c.danger("add it to your app target in Xcode")} ${c.muted("(drag into the project navigator) so bundled fallbacks ship in the binary")}`);
     }
     parseCatalog(path.resolve(cwd, catalogPath)); // fail fast if unparseable
     const name = flags.name ?? detectProjectName(cwd);
@@ -260,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");
@@ -292,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`);
@@ -313,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) {
@@ -332,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();
@@ -405,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),
@@ -440,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) {
@@ -498,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);
@@ -512,39 +833,18 @@ const SHADOW_CONTENT = `// Generated by \`polycast shadow\`: routes every plain
 import PolycastSDK
 typealias Text = PText
 `;
-/** Plant Polycast+Shadow.swift into each source module so plain Text —
- * and any design-system component built on it — renders OTA. */
+/** Plant Polycast+Shadow.swift once per Swift MODULE (a typealias is
+ * module-scoped; duplicates in the same module are compile errors).
+ * SPM packages get one per Sources/<target>; an Xcode app (no package
+ * boundary) is a single module and gets exactly one at its source root. */
 export async function shadow(args, _flags) {
     const { dir } = requireConfig();
-    let targets = args.map((a) => path.resolve(dir, a));
-    if (targets.length === 0) {
-        // Default: every directory that looks like a Swift source root.
-        const roots = new Set();
-        const walk = (d, depth) => {
-            if (depth > 5)
-                return;
-            let entries;
-            try {
-                entries = readdirSync(d);
-            }
-            catch {
-                return;
-            }
-            for (const name of entries) {
-                if (name.startsWith(".") || ["node_modules", "Pods", ".build", "build", "DerivedData"].includes(name))
-                    continue;
-                const full = path.join(d, name);
-                try {
-                    if (statSync(full).isDirectory())
-                        walk(full, depth + 1);
-                    else if (name.endsWith(".swift") && !name.startsWith("Polycast+") && name !== "Package.swift")
-                        roots.add(d);
-                }
-                catch { /* skip */ }
-            }
-        };
-        walk(dir, 0);
-        targets = [...roots];
+    let targets;
+    if (args.length > 0) {
+        targets = args.map((a) => path.resolve(dir, a));
+    }
+    else {
+        targets = detectModuleRoots(dir);
     }
     let planted = 0;
     for (const target of targets) {
@@ -552,16 +852,79 @@ export async function shadow(args, _flags) {
         if (existsSync(file))
             continue;
         writeFileSync(file, SHADOW_CONTENT);
-        console.log(`  ${S.ok}  ${path.relative(dir, file)}`);
+        console.log(`  ${S.ok}  ${path.relative(dir, file) || "Polycast+Shadow.swift"}`);
         planted++;
     }
     if (planted === 0) {
-        note("all source modules already shadowed");
+        note("all modules already shadowed");
         return;
     }
-    success(`planted ${planted} shadow file(s) — plain Text now renders OTA in those modules`);
+    success(`planted ${planted} shadow file(s) — plain Text now renders OTA`);
+    note("Xcode app targets: make sure the file is part of the target (drag into the navigator if needed)");
     note("using XcodeGen? re-run `xcodegen generate` so the new files join the project");
 }
+/** One root per Swift module. */
+function detectModuleRoots(root) {
+    const swiftDirs = [];
+    const packageDirs = [];
+    const walk = (d, depth) => {
+        if (depth > 6)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(d);
+        }
+        catch {
+            return;
+        }
+        if (entries.includes("Package.swift") && d !== root)
+            packageDirs.push(d);
+        for (const name of entries) {
+            if (name.startsWith(".") || ["node_modules", "Pods", ".build", "build", "DerivedData"].includes(name) || name.endsWith(".xcodeproj"))
+                continue;
+            const full = path.join(d, name);
+            try {
+                if (statSync(full).isDirectory())
+                    walk(full, depth + 1);
+                else if (name.endsWith(".swift") && !name.startsWith("Polycast+") && name !== "Package.swift")
+                    swiftDirs.push(d);
+            }
+            catch { /* skip */ }
+        }
+    };
+    walk(root, 0);
+    if (existsSync(path.join(root, "Package.swift")))
+        packageDirs.push(root);
+    const roots = new Set();
+    const inPackage = (d) => packageDirs.find((p) => d === p || d.startsWith(p + path.sep));
+    // SPM: one module per Sources/<target> directory.
+    for (const pkg of packageDirs) {
+        const sources = path.join(pkg, "Sources");
+        if (existsSync(sources)) {
+            for (const t of readdirSync(sources)) {
+                const td = path.join(sources, t);
+                try {
+                    if (statSync(td).isDirectory())
+                        roots.add(td);
+                }
+                catch { /* skip */ }
+            }
+        }
+    }
+    // Xcode app (everything outside package boundaries): ONE module — the
+    // common ancestor of its Swift dirs.
+    const appDirs = [...new Set(swiftDirs)].filter((d) => !inPackage(d));
+    if (appDirs.length > 0) {
+        let common = appDirs[0];
+        for (const d of appDirs) {
+            while (!(d === common || d.startsWith(common + path.sep))) {
+                common = path.dirname(common);
+            }
+        }
+        roots.add(common);
+    }
+    return [...roots];
+}
 // ---- gen ----
 function swiftIdent(part) {
     const cleaned = part.replace(/[^A-Za-z0-9]+(.)?/g, (_, c) => c ? c.toUpperCase() : "");