codz-cli 0.0.0-stage → 0.1.0

package/dist/adapters/android.js

@@ -0,0 +1,321 @@
+// Android adapter (Kotlin). Supported setup: an app module using Retrofit with
+// suspend functions, data classes for models (kotlinx.serialization, Moshi or
+// Gson), and Hilt, Koin or a hand-written service locator for registration;
+// Jetpack Compose with Navigation Compose for screens.
+//
+// Kotlin is edited with brace-aware text edits, like Dart: a method at the end
+// of an interface, a data class per model file, a provider in the network
+// module. Gradle files are edited only by setup (dependencies and plugins).
+import { join } from 'node:path';
+import { detectEol, exists, isDir, readText, walk, withEol } from "../core/fsutil.js";
+import { ToolError } from "../core/types.js";
+import { pascal, singular } from "../input/naming.js";
+import { emptyMap, fileStats, scanLocales, specRelativePath } from "./common.js";
+import { addKotlinImports, kotlinType, renderDataClass, renderRetrofitFun } from "./kotlinGen.js";
+import { referencedModels, resolveModels } from "./models.js";
+import { androidArchitectures, planAndroidSetup } from "./androidSetup.js";
+import { matchBrace } from "./source.js";
+export const ANDROID_VERSION = '0.1.0';
+export const ANDROID_CONVENTION_DOCS = {
+    module: 'the app module folder (usually app)',
+    namespace: 'the app package (namespace in build.gradle)',
+    srcDir: 'Kotlin source root of the app module',
+    http: 'HTTP client: retrofit (supported), ktor or none',
+    serialization: 'JSON library: kotlinx, moshi or gson',
+    di: 'how API interfaces are registered: hilt, koin, manual or none',
+    diFile: 'the Hilt module, Koin module or service locator that creates Retrofit',
+    ui: 'compose or views',
+    apiFolder: 'where Retrofit interfaces live',
+    modelsFolder: 'where data classes for API data live',
+    screensFolder: 'where Compose screens live',
+    navFile: 'the file with the Compose NavHost',
+    baseUrl: 'Retrofit base URL found in the code, if it is a literal',
+    versionCatalog: 'gradle/libs.versions.toml, when the project uses one',
+    indent: 'indentation used in Kotlin files',
+};
+const dirOf = (f) => f.slice(0, f.lastIndexOf('/'));
+const mostCommon = (xs, fallback) => {
+    const n = new Map();
+    for (const x of xs)
+        n.set(x, (n.get(x) ?? 0) + 1);
+    return [...n.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? fallback;
+};
+/** The package a Kotlin file under srcDir belongs to. */
+export function packageOf(srcDir, dir) {
+    return dir.slice(srcDir.length + 1).replace(/\//g, '.');
+}
+/** The app module: a folder whose build file applies the Android application plugin. */
+export function findAppModule(root) {
+    for (const m of ['app', ...walk(root, '.', { exts: ['build.gradle.kts', 'build.gradle'], maxFiles: 2000 }).map(dirOf).filter((d) => d && !d.includes('/'))]) {
+        const t = readText(join(root, m, 'build.gradle.kts')) ?? readText(join(root, m, 'build.gradle'));
+        if (t && /com\.android\.application|android\.application/.test(t))
+            return m;
+    }
+    return null;
+}
+const RETROFIT_FUN = /@(GET|POST|PUT|PATCH|DELETE|HEAD)\(\s*"([^"]*)"\s*\)\s*(?:@\w+(?:\([^)]*\))?\s*)*(?:suspend\s+)?fun\s+(\w+)\s*\(/g;
+function parseDataClasses(text, file) {
+    const out = [];
+    for (const m of text.matchAll(/\bdata\s+class\s+(\w+)\s*\(/g)) {
+        const open = m.index + m[0].length - 1;
+        const close = matchBrace(text, open, 'dart');
+        if (close === -1)
+            continue;
+        const fields = [];
+        for (const p of text.slice(open + 1, close).split(/,(?![^<(]*[>)])/)) {
+            const json = /@(?:SerialName|SerializedName)\(\s*"([^"]+)"\s*\)|@Json\(\s*name\s*=\s*"([^"]+)"\s*\)/.exec(p);
+            const f = /\b(?:val|var)\s+`?(\w+)`?\s*:\s*([\w<>?, .]+?)\s*(?:=|$)/.exec(p.replace(/\/\/[^\n]*/g, '').trim());
+            if (!f)
+                continue;
+            const type = f[2].trim();
+            fields.push({ name: json?.[1] ?? json?.[2] ?? f[1], type: type.replace(/\?$/, ''), nullable: type.endsWith('?') });
+        }
+        out.push({ name: m[1], file, fields });
+    }
+    return out;
+}
+async function scan(root, configConventions) {
+    const map = emptyMap('android', `android@${ANDROID_VERSION}`);
+    const files = walk(root, '.', { extraIgnored: ['build', '.gradle', '.idea'] });
+    map.stats = fileStats(files);
+    const c = {};
+    const module = findAppModule(root) ?? 'app';
+    c.module = module;
+    const buildFile = ['build.gradle.kts', 'build.gradle'].map((f) => `${module}/${f}`).find((f) => exists(join(root, f))) ?? `${module}/build.gradle.kts`;
+    const build = readText(join(root, buildFile)) ?? '';
+    const catalog = readText(join(root, 'gradle/libs.versions.toml')) ?? '';
+    c.versionCatalog = catalog ? 'gradle/libs.versions.toml' : '';
+    const manifest = readText(join(root, module, 'src/main/AndroidManifest.xml')) ?? '';
+    c.namespace = /namespace\s*=?\s*["']([\w.]+)["']/.exec(build)?.[1] ?? /package\s*=\s*"([\w.]+)"/.exec(manifest)?.[1] ?? '';
+    c.srcDir = [`${module}/src/main/kotlin`, `${module}/src/main/java`].find((d) => isDir(join(root, d)) && (!c.namespace || isDir(join(root, d, ...c.namespace.split('.'))))) ?? `${module}/src/main/java`;
+    const pkgDir = c.namespace ? `${c.srcDir}/${c.namespace.replace(/\./g, '/')}` : c.srcDir;
+    const deps = `${build}\n${catalog}`;
+    c.http = /com\.squareup\.retrofit2/.test(deps) ? 'retrofit' : /io\.ktor/.test(deps) ? 'ktor' : 'none';
+    c.serialization = /org\.jetbrains\.kotlinx[:"].*serialization|kotlinx-serialization-json/.test(deps) ? 'kotlinx' : /com\.squareup\.moshi/.test(deps) ? 'moshi' : /com\.google\.code\.gson|converter-gson/.test(deps) ? 'gson' : 'kotlinx';
+    c.di = /com\.google\.dagger[:"].*hilt|com\.google\.dagger\.hilt\.android/.test(deps) ? 'hilt' : /io\.insert-koin/.test(deps) ? 'koin' : 'none';
+    c.ui = /compose\s*=\s*true|androidx\.compose|compose-bom/.test(deps) ? 'compose' : 'views';
+    const kt = files.filter((f) => f.startsWith(`${c.srcDir}/`) && f.endsWith('.kt'));
+    const text = (f) => readText(join(root, f)) ?? '';
+    const apiFiles = kt.filter((f) => /^\s*interface\s+\w+/m.test(text(f)) && RETROFIT_FUN.test(text(f)) && ((RETROFIT_FUN.lastIndex = 0), true));
+    c.apiFolder = mostCommon(apiFiles.map(dirOf), `${pkgDir}/data/remote`);
+    const modelFiles = kt.filter((f) => /\bdata\s+class\b/.test(text(f)) && /@Serializable|@JsonClass|@SerializedName|@SerialName/.test(text(f)));
+    c.modelsFolder = mostCommon(modelFiles.map(dirOf), `${pkgDir}/data/model`);
+    for (const f of modelFiles)
+        map.models.push(...parseDataClasses(text(f), f));
+    const retrofitFile = kt.find((f) => /Retrofit\.Builder\(\)/.test(text(f)));
+    c.diFile =
+        (c.di === 'hilt' ? kt.find((f) => /@Module\b/.test(text(f)) && /Retrofit/.test(text(f))) : c.di === 'koin' ? kt.find((f) => /\bmodule\s*\{/.test(text(f)) && /Retrofit/.test(text(f))) : retrofitFile) ?? '';
+    if (c.di === 'none' && retrofitFile && /\bobject\s+\w+/.test(text(retrofitFile)))
+        c.di = 'manual';
+    c.baseUrl = retrofitFile ? /\.baseUrl\(\s*"([^"]+)"\s*\)/.exec(text(retrofitFile))?.[1] ?? /BASE_URL\s*=\s*"([^"]+)"/.exec(text(retrofitFile))?.[1] ?? '' : '';
+    if (!c.baseUrl)
+        for (const f of kt) {
+            const m = /\bBASE_URL\s*=\s*"(https?:[^"]+)"/.exec(text(f));
+            if (m) {
+                c.baseUrl = m[1];
+                break;
+            }
+        }
+    if (!c.baseUrl)
+        c.baseUrl = /buildConfigField\(\s*"String"\s*,\s*"BASE_URL"\s*,\s*"\\"([^"\\]+)\\""\s*\)/.exec(build)?.[1] ?? '';
+    const screens = kt.filter((f) => /@Composable\s+fun\s+\w+Screen\s*\(/.test(text(f)));
+    c.screensFolder = mostCommon(screens.map(dirOf), `${pkgDir}/ui/screens`);
+    c.navFile = kt.find((f) => /\bNavHost\s*\(/.test(text(f))) ?? '';
+    c.indent = /\n {2}\S/.test(kt.slice(0, 10).map(text).join('\n')) && !/\n {4}\S/.test(kt.slice(0, 10).map(text).join('\n')) ? '2' : '4';
+    map.conventions = { ...c, ...configConventions };
+    const conv = map.conventions;
+    if (conv.http !== 'retrofit')
+        map.notes.push(conv.http === 'ktor' ? 'This project uses Ktor; api add writes Retrofit interfaces only so far.' : 'No HTTP client found; codz setup adds Retrofit.');
+    if (!conv.namespace)
+        map.notes.push('No namespace found in the app build file, so package names cannot be worked out.');
+    for (const f of apiFiles) {
+        const t = text(f);
+        for (const m of t.matchAll(RETROFIT_FUN)) {
+            const close = matchBrace(t, m.index + m[0].length - 1, 'dart');
+            const ret = close === -1 ? '' : /^\s*:\s*([\w<>?, .]+)/.exec(t.slice(close + 1))?.[1]?.trim() ?? 'Unit';
+            map.endpoints.push({ name: m[3], method: m[1], path: `/${m[2].replace(/^\//, '')}`, response: ret, file: f, calledFrom: [] });
+        }
+    }
+    for (const f of kt) {
+        const t = text(f);
+        for (const ep of map.endpoints)
+            if (ep.file !== f && new RegExp(`\\.${ep.name}\\s*\\(`).test(t))
+                ep.calledFrom.push(f);
+    }
+    // Compose routes: composable("orders/{id}") { ... }
+    for (const f of kt)
+        for (const m of text(f).matchAll(/\bcomposable\(\s*(?:route\s*=\s*)?"([^"]+)"/g))
+            map.routes.push({ name: m[1].split('/')[0], path: `/${m[1]}`, params: [...m[1].matchAll(/\{(\w+)\}/g)].map((x) => x[1]), file: f });
+    map.locales = scanLocales(root, files);
+    return map;
+}
+const resourceOf = (path) => path.split('/').filter((s) => s && !s.startsWith('{') && !/^(api|v\d+)$/i.test(s))[0] ?? 'root';
+/** Registers a new Retrofit interface where Retrofit is created. */
+function register(files, read, c, iface, ifacePkg, summary, warnings) {
+    const di = c.diFile;
+    const text = di ? read(di) : null;
+    if (!di || text === null) {
+        warnings.push(`No ${c.di === 'none' ? 'Retrofit setup' : `${c.di} module`} was found, so ${iface} is not registered. Create it with retrofit.create(${iface}::class.java), or run codz setup.`);
+        return;
+    }
+    const fn = iface[0].toLowerCase() + iface.slice(1);
+    let t = text;
+    if (new RegExp(`\\b${iface}::class`).test(t))
+        return;
+    const pkg = /^package\s+([\w.]+)/m.exec(t)?.[1] ?? '';
+    if (c.di === 'hilt') {
+        const obj = /\bobject\s+\w+\s*\{/.exec(t);
+        if (!obj)
+            return void warnings.push(`Could not find the Hilt module object in ${di}; add @Provides fun provide${iface}(retrofit: Retrofit): ${iface} = retrofit.create(${iface}::class.java).`);
+        const close = matchBrace(t, obj.index + obj[0].length - 1, 'dart');
+        t = `${t.slice(0, close).replace(/\s*$/, '\n')}\n    @Provides\n    @Singleton\n    fun provide${iface}(retrofit: Retrofit): ${iface} = retrofit.create(${iface}::class.java)\n${t.slice(close)}`;
+        t = addKotlinImports(t, [`${ifacePkg}.${iface}`, 'dagger.Provides', 'javax.inject.Singleton', 'retrofit2.Retrofit'], pkg);
+    }
+    else if (c.di === 'koin') {
+        const singles = [...t.matchAll(/^([ \t]*)single(?:<[^>]*>)?\s*\{[^\n]*\}\s*$/gm)];
+        if (!singles.length)
+            return void warnings.push(`Could not find a single { } in ${di}; add single { get<Retrofit>().create(${iface}::class.java) }.`);
+        const last = singles[singles.length - 1];
+        const at = last.index + last[0].length;
+        t = `${t.slice(0, at)}\n${last[1]}single { get<Retrofit>().create(${iface}::class.java) }${t.slice(at)}`;
+        t = addKotlinImports(t, [`${ifacePkg}.${iface}`, 'retrofit2.Retrofit'], pkg);
+    }
+    else {
+        const obj = /\bobject\s+\w+\s*\{/.exec(t);
+        const retrofitVal = /\bval\s+(\w+)\s*:\s*Retrofit\b/.exec(t)?.[1] ?? /\bval\s+(\w+)\s*=\s*Retrofit\.Builder/.exec(t)?.[1] ?? 'retrofit';
+        if (!obj)
+            return void warnings.push(`Could not find the service locator object in ${di}; add val ${fn}: ${iface} = retrofit.create(${iface}::class.java).`);
+        const close = matchBrace(t, obj.index + obj[0].length - 1, 'dart');
+        t = `${t.slice(0, close).replace(/\s*$/, '\n')}\n    val ${fn}: ${iface} by lazy { ${retrofitVal}.create(${iface}::class.java) }\n${t.slice(close)}`;
+        t = addKotlinImports(t, [`${ifacePkg}.${iface}`], pkg);
+    }
+    files.set(di, withEol(t, detectEol(text)));
+    summary.push(`Update ${di}: register ${iface} with ${c.di === 'manual' ? 'the service locator' : c.di}`);
+}
+async function planEndpoint(ctx, input, overlay, opts = {}) {
+    const { root, map } = ctx;
+    const c = map.conventions;
+    if (c.http !== 'retrofit')
+        throw new ToolError('unsupported_setup', c.http === 'ktor' ? 'This project uses Ktor; the Android adapter writes Retrofit interfaces only so far.' : 'This project has no Retrofit yet.', 'Run codz setup to add Retrofit, or add it yourself.');
+    if (!c.namespace)
+        throw new ToolError('no_package', 'No namespace was found in the app build file, so package names cannot be written.', 'Set namespace in codz.config.yaml.');
+    if (input.unwrapData)
+        throw new ToolError('unsupported_setup', 'This response wraps its data in {"data": ...}, and a Retrofit method returns the whole body.', 'Run again with --no-unwrap to generate a model for the whole body.');
+    const files = new Map(overlay ?? []);
+    const read = (p) => files.get(p) ?? readText(join(root, p));
+    const summary = [];
+    const warnings = [...input.warnings];
+    const { spec, reused, replaced, notes } = resolveModels(input, map.models, (n) => n, { replace: opts.replaceModels });
+    warnings.push(...notes);
+    const srcDir = c.srcDir || 'app/src/main/java';
+    // Path relative to the base URL.
+    let path = spec.path;
+    // Retrofit always has a base URL; an endpoint from an API spec is relative to it (the spec's server stands in for it).
+    const fromSpec = specRelativePath(spec, c.baseUrl);
+    if (fromSpec !== null) {
+        path = fromSpec;
+        if (c.baseUrl && !c.baseUrl.endsWith('/'))
+            warnings.push(`Retrofit needs the base URL to end with "/" (${c.baseUrl}).`);
+    }
+    else if (c.baseUrl) {
+        try {
+            const b = new URL(c.baseUrl);
+            const prefix = b.pathname.replace(/\/$/, '');
+            if ((!spec.origin || spec.origin === b.origin) && prefix && path.startsWith(prefix))
+                path = path.slice(prefix.length) || '/';
+            else if (spec.origin && spec.origin !== b.origin) {
+                path = `${spec.origin}${spec.path}`;
+                warnings.push(`The URL host ${spec.origin} differs from the Retrofit base URL (${c.baseUrl}), so the full URL is used for this call.`);
+            }
+        }
+        catch {
+            // Not a literal URL.
+        }
+        if (!c.baseUrl.endsWith('/'))
+            warnings.push(`Retrofit needs the base URL to end with "/" (${c.baseUrl}).`);
+    }
+    const existing = map.endpoints.find((e) => e.name === spec.name);
+    if (existing) {
+        if (existing.method === spec.method && existing.path.replace(/\{\w+\}/g, '{}') === path.replace(/\{\w+\}/g, '{}'))
+            return { files, summary: [`${spec.name} already exists in ${existing.file}; nothing to do.`], warnings: [], generated: [] };
+        throw new ToolError('name_conflict', `A function called ${spec.name} already exists in ${existing.file} for ${existing.method} ${existing.path}.`, 'Pass --name <functionName> to use another name.');
+    }
+    // Models: one data class per file.
+    const modelFile = new Map();
+    for (const [name, info] of reused)
+        modelFile.set(name, info.file);
+    const modelsPkg = packageOf(srcDir, c.modelsFolder || `${srcDir}/${c.namespace.replace(/\./g, '/')}/data/model`);
+    for (const m of spec.models) {
+        const file = replaced.get(m.name)?.file ?? `${c.modelsFolder}/${m.name}.kt`;
+        modelFile.set(m.name, file);
+        const prev = read(file);
+        if (prev !== null && !replaced.has(m.name))
+            throw new ToolError('file_exists', `${file} already exists but does not define ${m.name}.`, 'Pass --model-name <Name> to use another name.');
+        let content = renderDataClass(m, c, packageOf(srcDir, dirOf(file)));
+        const deps = new Set();
+        for (const f of m.fields)
+            referencedModels(f.type, deps);
+        content = addKotlinImports(content, [...deps].map((d) => modelFile.get(d)).filter((f) => !!f && dirOf(f) !== dirOf(file)).map((f) => `${packageOf(srcDir, dirOf(f))}.${f.slice(f.lastIndexOf('/') + 1, -3)}`), packageOf(srcDir, dirOf(file)));
+        if (prev !== null && replaced.has(m.name)) {
+            // Rewrite just this class, keeping the rest of the file.
+            const start = prev.search(new RegExp(`(?:@\\w+(?:\\([^)]*\\))?\\s*\\n)*data\\s+class\\s+${m.name}\\b`));
+            const open = prev.indexOf('(', start);
+            const close = matchBrace(prev, open, 'dart');
+            let end = close + 1;
+            if (prev[end] === ' ' && prev[end + 1] === '{')
+                end = matchBrace(prev, end + 1, 'dart') + 1;
+            const cls = content.slice(content.search(/^(@Serializable|@JsonClass|data class)/m)).replace(/\n$/, '');
+            content = addKotlinImports(prev.slice(0, start) + cls + prev.slice(end), [...content.matchAll(/^import\s+([\w.]+)/gm)].map((x) => x[1]), packageOf(srcDir, dirOf(file)));
+        }
+        files.set(file, content);
+        summary.push(`${prev === null ? 'Create' : 'Update'} ${file}: data class ${m.name}${replaced.has(m.name) ? ' (rewritten)' : ''}`);
+    }
+    void modelsPkg;
+    // Retrofit interface.
+    const resource = resourceOf(spec.path);
+    const iface = `${pascal(singular(resource))}Api`;
+    const fromEndpoints = map.endpoints.find((e) => resourceOf(e.path) === resource)?.file;
+    let apiFile = opts.targetFile ?? fromEndpoints ?? `${c.apiFolder}/${iface}.kt`;
+    const apiPkg = packageOf(srcDir, dirOf(apiFile));
+    let apiText = read(apiFile);
+    const created = apiText === null;
+    if (created)
+        apiText = `package ${apiPkg}\n\ninterface ${iface} {\n}\n`;
+    const ifaceName = /\binterface\s+(\w+)/.exec(apiText)?.[1] ?? iface;
+    const fun = renderRetrofitFun(spec, c, path);
+    const head = /\binterface\s+\w+[^{]*\{/.exec(apiText);
+    const close = matchBrace(apiText, head.index + head[0].length - 1, 'dart');
+    const before = apiText.slice(0, close).replace(/\s*$/, '');
+    apiText = `${before}${before.endsWith('{') ? '\n' : '\n\n'}${fun.code}\n${apiText.slice(close)}`;
+    const typeRefs = new Set();
+    referencedModels(spec.response, typeRefs);
+    referencedModels(spec.request, typeRefs);
+    const modelImports = [...typeRefs].map((t) => modelFile.get(t) ?? map.models.find((m) => m.name === t)?.file).filter((f) => !!f).map((f) => `${packageOf(srcDir, dirOf(f))}.${f.slice(f.lastIndexOf('/') + 1, -3)}`);
+    apiText = addKotlinImports(apiText, [...fun.imports, ...modelImports], apiPkg);
+    files.set(apiFile, apiText);
+    summary.push(`${created ? 'Create' : 'Update'} ${apiFile}: ${ifaceName}.${spec.name}() for ${spec.method} ${spec.path}`);
+    if (created)
+        register(files, read, c, ifaceName, apiPkg, summary, warnings);
+    void apiFile;
+    return {
+        files,
+        summary,
+        warnings,
+        generated: [{ skill: 'api add', file: apiFile, symbol: spec.name, inputHash: '' }],
+        endpoints: [{ name: spec.name, method: spec.method, path: `/${path.replace(/^\//, '')}`, response: spec.method === 'DELETE' || spec.method === 'HEAD' ? 'Unit' : spec.response ? kotlinType(spec.response, c) : 'Any', file: apiFile, calledFrom: [] }],
+        models: spec.models.map((m) => ({ name: m.name, file: modelFile.get(m.name), fields: m.fields.map((f) => ({ name: f.jsonName, type: kotlinType(f.type, c), nullable: f.nullable })) })),
+    };
+}
+export const androidAdapter = {
+    id: 'android',
+    version: ANDROID_VERSION,
+    capabilities: { explain: true, apiAdd: true },
+    supportedSetup: 'Android (Kotlin): Retrofit with suspend functions; kotlinx.serialization, Moshi or Gson data classes; Hilt, Koin or a service locator; screens in Jetpack Compose (Navigation Compose) or XML Views (Activities). Not yet: Ktor, Java sources, Fragments.',
+    scan,
+    planEndpoint,
+    architectures: androidArchitectures,
+    planSetup: planAndroidSetup,
+    afterSetup: () => null,
+    formatCommand: () => null,
+    verifyCommand: () => null,
+};

package/dist/adapters/androidSetup.js

@@ -0,0 +1,277 @@
+// Android `setup`: Retrofit, OkHttp and kotlinx.serialization for an app that
+// has no API layer yet, registered one of three ways:
+//
+//   retrofit-hilt   NetworkModule (@Module @InstallIn(SingletonComponent)),
+//                   @HiltAndroidApp application, @AndroidEntryPoint activity
+//   retrofit-koin   networkModule = module { ... }, startKoin in the application
+//   retrofit        ServiceLocator object (no DI library)
+//
+// Gradle: dependencies and plugins go into gradle/libs.versions.toml and the
+// module's build.gradle.kts when the project uses a version catalog (new
+// Android Studio projects do), otherwise straight into build.gradle.kts.
+import { join } from 'node:path';
+import { readText } from "../core/fsutil.js";
+import { ToolError } from "../core/types.js";
+import { addKotlinImports } from "./kotlinGen.js";
+/** Versions known to work together (Kotlin 2.0, AGP 8.7). */
+export const ANDROID_VERSIONS = {
+    kotlin: '2.0.21',
+    ksp: '2.0.21-1.0.28',
+    retrofit: '2.11.0',
+    okhttp: '4.12.0',
+    serialization: '1.7.3',
+    hilt: '2.52',
+    hiltNavigationCompose: '1.2.0',
+    koin: '4.0.0',
+    lifecycle: '2.8.7',
+    navigationCompose: '2.8.4',
+};
+const LIBS = {
+    retrofit: { key: 'retrofit', coord: 'com.squareup.retrofit2:retrofit', version: 'retrofit' },
+    retrofitKotlinx: { key: 'retrofit-kotlinx-serialization', coord: 'com.squareup.retrofit2:converter-kotlinx-serialization', version: 'retrofit' },
+    okhttpLogging: { key: 'okhttp-logging', coord: 'com.squareup.okhttp3:logging-interceptor', version: 'okhttp' },
+    serialization: { key: 'kotlinx-serialization-json', coord: 'org.jetbrains.kotlinx:kotlinx-serialization-json', version: 'serialization' },
+    hilt: { key: 'hilt-android', coord: 'com.google.dagger:hilt-android', version: 'hilt' },
+    hiltCompiler: { key: 'hilt-compiler', coord: 'com.google.dagger:hilt-compiler', version: 'hilt', config: 'ksp' },
+    hiltNav: { key: 'hilt-navigation-compose', coord: 'androidx.hilt:hilt-navigation-compose', version: 'hiltNavigationCompose' },
+    koin: { key: 'koin-android', coord: 'io.insert-koin:koin-android', version: 'koin' },
+    koinCompose: { key: 'koin-androidx-compose', coord: 'io.insert-koin:koin-androidx-compose', version: 'koin' },
+    viewModelCompose: { key: 'androidx-lifecycle-viewmodel-compose', coord: 'androidx.lifecycle:lifecycle-viewmodel-compose', version: 'lifecycle' },
+    navigationCompose: { key: 'androidx-navigation-compose', coord: 'androidx.navigation:navigation-compose', version: 'navigationCompose' },
+};
+const PLUGINS = {
+    serialization: { key: 'kotlin-serialization', id: 'org.jetbrains.kotlin.plugin.serialization', version: 'kotlin', root: true },
+    hilt: { key: 'hilt', id: 'com.google.dagger.hilt.android', version: 'hilt', root: true },
+    ksp: { key: 'ksp', id: 'com.google.devtools.ksp', version: 'ksp', root: true },
+};
+export function androidArchitectures(map) {
+    if (map.endpoints.length > 0 || map.conventions.http === 'retrofit')
+        return [];
+    return [
+        { id: 'retrofit-hilt', label: 'Retrofit + Hilt', description: 'NetworkModule provides Retrofit and every API interface; @HiltAndroidApp', recommended: true },
+        { id: 'retrofit-koin', label: 'Retrofit + Koin', description: 'networkModule with single { } definitions; startKoin in the Application class', recommended: false },
+        { id: 'retrofit', label: 'Retrofit only', description: 'A ServiceLocator object holds Retrofit and the API interfaces; no DI library', recommended: false },
+    ];
+}
+const tomlKey = (k) => k.replace(/-/g, '.');
+/** Adds entries to a [section] of libs.versions.toml, unless the key is there. */
+export function tomlAdd(text, section, entries) {
+    let t = text;
+    const head = new RegExp(`^\\[${section}\\]\\s*$`, 'm').exec(t);
+    if (!head)
+        t = `${t.replace(/\s*$/, '\n')}\n[${section}]\n`;
+    for (const [k, v] of entries) {
+        const h = new RegExp(`^\\[${section}\\]\\s*$`, 'm').exec(t);
+        const next = t.slice(h.index + h[0].length).search(/^\[/m);
+        const at = next === -1 ? t.length : h.index + h[0].length + next;
+        // Only this section counts: [versions] often has a key with the same name.
+        if (new RegExp(`^${k.replace(/[.-]/g, '[.-]')}\\s*=`, 'm').test(t.slice(h.index, at)))
+            continue;
+        const before = t.slice(0, at).replace(/\n*$/, '\n');
+        t = `${before}${k} = ${v}\n${next === -1 ? '' : '\n'}${t.slice(at).replace(/^\n+/, '')}`;
+    }
+    return t;
+}
+/** Adds lines to the first `name { ... }` block of a Gradle Kotlin script. */
+export function gradleBlockAdd(text, block, lines) {
+    const m = new RegExp(`^${block}\\s*\\{`, 'm').exec(text);
+    const want = lines.filter((l) => !text.includes(l.trim()));
+    if (!want.length)
+        return text;
+    if (!m)
+        return `${text.replace(/\s*$/, '\n')}\n${block} {\n${want.map((l) => `    ${l}`).join('\n')}\n}\n`;
+    let depth = 0;
+    let i = m.index + m[0].length - 1;
+    for (; i < text.length; i++) {
+        if (text[i] === '{')
+            depth++;
+        else if (text[i] === '}' && --depth === 0)
+            break;
+    }
+    const before = text.slice(0, i).replace(/\s*$/, '\n');
+    return `${before}${want.map((l) => `    ${l}`).join('\n')}\n${text.slice(i)}`;
+}
+function networkFile(arch, pkg) {
+    const imports = ['kotlinx.serialization.json.Json', 'okhttp3.MediaType.Companion.toMediaType', 'okhttp3.OkHttpClient', 'okhttp3.logging.HttpLoggingInterceptor', 'retrofit2.Retrofit', 'retrofit2.converter.kotlinx.serialization.asConverterFactory'];
+    const logging = 'HttpLoggingInterceptor().apply { level = HttpLoggingInterceptor.Level.BODY }';
+    let body;
+    if (arch === 'retrofit-hilt') {
+        imports.push('dagger.Module', 'dagger.Provides', 'dagger.hilt.InstallIn', 'dagger.hilt.components.SingletonComponent', 'javax.inject.Singleton');
+        body = [
+            '/** Creates Retrofit and every API interface. codz api add adds a provider here for each new interface. */',
+            '@Module',
+            '@InstallIn(SingletonComponent::class)',
+            'object NetworkModule {',
+            '    @Provides',
+            '    @Singleton',
+            '    fun provideJson(): Json = Json { ignoreUnknownKeys = true }',
+            '',
+            '    @Provides',
+            '    @Singleton',
+            '    fun provideOkHttpClient(): OkHttpClient =',
+            '        OkHttpClient.Builder()',
+            `            .addInterceptor(${logging})`,
+            '            .build()',
+            '',
+            '    @Provides',
+            '    @Singleton',
+            '    fun provideRetrofit(client: OkHttpClient, json: Json): Retrofit =',
+            '        Retrofit.Builder()',
+            '            .baseUrl(ApiConfig.BASE_URL)',
+            '            .client(client)',
+            '            .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))',
+            '            .build()',
+            '}',
+        ];
+    }
+    else if (arch === 'retrofit-koin') {
+        imports.push('org.koin.dsl.module');
+        body = [
+            '/** Retrofit and every API interface. codz api add adds a single { } here for each new interface. */',
+            'val networkModule = module {',
+            '    single { Json { ignoreUnknownKeys = true } }',
+            `    single { OkHttpClient.Builder().addInterceptor(${logging}).build() }`,
+            '    single { Retrofit.Builder().baseUrl(ApiConfig.BASE_URL).client(get<OkHttpClient>()).addConverterFactory(get<Json>().asConverterFactory("application/json".toMediaType())).build() }',
+            '}',
+        ];
+    }
+    else {
+        body = [
+            '/** Holds Retrofit and the API interfaces. codz api add adds one val per new interface. */',
+            'object ServiceLocator {',
+            '    private val json = Json { ignoreUnknownKeys = true }',
+            '',
+            '    private val client: OkHttpClient by lazy {',
+            `        OkHttpClient.Builder().addInterceptor(${logging}).build()`,
+            '    }',
+            '',
+            '    val retrofit: Retrofit by lazy {',
+            '        Retrofit.Builder()',
+            '            .baseUrl(ApiConfig.BASE_URL)',
+            '            .client(client)',
+            '            .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))',
+            '            .build()',
+            '    }',
+            '}',
+        ];
+    }
+    return addKotlinImports([`package ${pkg}`, '', ...body, ''].join('\n'), imports, pkg);
+}
+export function planAndroidSetup(ctx, choice) {
+    const { root, map } = ctx;
+    if (!['retrofit-hilt', 'retrofit-koin', 'retrofit'].includes(choice.architecture))
+        throw new ToolError('bad_args', `Unknown architecture "${choice.architecture}". Choose retrofit-hilt, retrofit-koin or retrofit.`);
+    const c0 = map.conventions;
+    if (!c0.namespace)
+        throw new ToolError('no_package', 'No namespace was found in the app build file, so setup cannot write Kotlin packages.', 'Add namespace = "com.example.app" to the android { } block.');
+    const files = new Map();
+    const summary = [];
+    const warnings = [];
+    const read = (p) => files.get(p) ?? readText(join(root, p));
+    const module = c0.module || 'app';
+    const srcDir = c0.srcDir || `${module}/src/main/java`;
+    const pkg = c0.namespace;
+    const pkgDir = `${srcDir}/${pkg.replace(/\./g, '/')}`;
+    const baseUrl = (choice.baseUrl || 'https://api.example.com').replace(/\/?$/, '/');
+    if (!choice.baseUrl)
+        warnings.push(`No base URL was given, so ApiConfig.BASE_URL is https://api.example.com/. Change it before calling the API.`);
+    const arch = choice.architecture;
+    const create = (path, content, what) => {
+        if (read(path) !== null)
+            throw new ToolError('file_exists', `${path} already exists, so setup stopped without changing anything.`);
+        files.set(path, content);
+        summary.push(`Create ${path}: ${what}`);
+    };
+    const remotePkg = `${pkg}.data.remote`;
+    const diPkg = `${pkg}.di`;
+    create(`${pkgDir}/data/remote/ApiConfig.kt`, `package ${remotePkg}\n\nobject ApiConfig {\n    /** Must end with "/": Retrofit paths are relative to it. */\n    const val BASE_URL = "${baseUrl}"\n}\n`, `BASE_URL = ${baseUrl}`);
+    const netFile = arch === 'retrofit' ? `${pkgDir}/data/remote/ServiceLocator.kt` : `${pkgDir}/di/NetworkModule.kt`;
+    create(netFile, addKotlinImports(networkFile(arch, arch === 'retrofit' ? remotePkg : diPkg), arch === 'retrofit' ? [] : [`${remotePkg}.ApiConfig`], arch === 'retrofit' ? remotePkg : diPkg), arch === 'retrofit-hilt' ? 'Hilt NetworkModule: Json, OkHttpClient, Retrofit' : arch === 'retrofit-koin' ? 'Koin networkModule: Json, OkHttpClient, Retrofit' : 'ServiceLocator with Retrofit');
+    // Application class and manifest.
+    const manifestPath = `${module}/src/main/AndroidManifest.xml`;
+    let manifest = read(manifestPath);
+    if (arch !== 'retrofit') {
+        const appFile = `${pkgDir}/App.kt`;
+        const app = arch === 'retrofit-hilt'
+            ? `package ${pkg}\n\nimport android.app.Application\nimport dagger.hilt.android.HiltAndroidApp\n\n@HiltAndroidApp\nclass App : Application()\n`
+            : `package ${pkg}\n\nimport android.app.Application\nimport ${diPkg}.networkModule\nimport org.koin.android.ext.koin.androidContext\nimport org.koin.core.context.startKoin\n\nclass App : Application() {\n    override fun onCreate() {\n        super.onCreate()\n        startKoin {\n            androidContext(this@App)\n            modules(networkModule)\n        }\n    }\n}\n`;
+        if (manifest && /android:name="\.?\w*App\w*"/.test(manifest.split('<activity')[0]))
+            warnings.push(`${manifestPath} already names an Application class; ${arch === 'retrofit-hilt' ? 'annotate it with @HiltAndroidApp' : 'call startKoin { modules(networkModule) } from it'} instead of the new App.kt.`);
+        else {
+            create(appFile, app, arch === 'retrofit-hilt' ? '@HiltAndroidApp application' : 'application that starts Koin');
+            if (manifest)
+                manifest = manifest.replace(/<application\b/, '<application\n        android:name=".App"');
+        }
+        if (arch === 'retrofit-hilt') {
+            const main = [`${pkgDir}/MainActivity.kt`].find((f) => read(f) !== null);
+            // Hilt injects only into ComponentActivity subclasses (AppCompatActivity, FragmentActivity), not android.app.Activity.
+            const hiltable = main ? /class\s+MainActivity\s*:\s*(ComponentActivity|AppCompatActivity|FragmentActivity)\b/.test(read(main)) : false;
+            if (main && !hiltable && !/@AndroidEntryPoint/.test(read(main)))
+                warnings.push(`${main} extends a class Hilt cannot inject into; if it needs injected objects, make it extend ComponentActivity and add @AndroidEntryPoint.`);
+            if (main && hiltable && !/@AndroidEntryPoint/.test(read(main))) {
+                files.set(main, addKotlinImports(read(main).replace(/^class\s+MainActivity/m, '@AndroidEntryPoint\nclass MainActivity'), ['dagger.hilt.android.AndroidEntryPoint'], pkg));
+                summary.push(`Update ${main}: @AndroidEntryPoint`);
+            }
+        }
+    }
+    if (manifest !== null) {
+        if (!/android\.permission\.INTERNET/.test(manifest))
+            manifest = manifest.replace(/(<manifest\b[^>]*>)/, '$1\n\n    <uses-permission android:name="android.permission.INTERNET" />');
+        if (manifest !== readText(join(root, manifestPath))) {
+            files.set(manifestPath, manifest);
+            summary.push(`Update ${manifestPath}: INTERNET permission${arch !== 'retrofit' ? ' and android:name=".App"' : ''}`);
+        }
+    }
+    // Gradle.
+    const libs = [LIBS.retrofit, LIBS.retrofitKotlinx, LIBS.okhttpLogging, LIBS.serialization, ...(c0.ui === 'compose' ? [LIBS.viewModelCompose, LIBS.navigationCompose] : []), ...(arch === 'retrofit-hilt' ? [LIBS.hilt, LIBS.hiltCompiler, ...(c0.ui === 'compose' ? [LIBS.hiltNav] : [])] : []), ...(arch === 'retrofit-koin' ? [LIBS.koin, ...(c0.ui === 'compose' ? [LIBS.koinCompose] : [])] : [])];
+    const plugins = [PLUGINS.serialization, ...(arch === 'retrofit-hilt' ? [PLUGINS.ksp, PLUGINS.hilt] : [])];
+    const catalogPath = c0.versionCatalog || '';
+    const moduleBuild = [`${module}/build.gradle.kts`, `${module}/build.gradle`].find((f) => read(f) !== null);
+    const rootBuild = ['build.gradle.kts', 'build.gradle'].find((f) => read(f) !== null);
+    let catalog = catalogPath ? read(catalogPath) : null;
+    const kotlinVersion = (catalog && /^kotlin\s*=\s*"([^"]+)"/m.exec(catalog)?.[1]) || ANDROID_VERSIONS.kotlin;
+    const version = (k) => (k === 'kotlin' ? kotlinVersion : ANDROID_VERSIONS[k]);
+    if (moduleBuild && !moduleBuild.endsWith('.kts'))
+        warnings.push(`${moduleBuild} is Groovy; add these dependencies yourself: ${libs.map((l) => `${l.coord}:${version(l.version)}`).join(', ')}.`);
+    else if (moduleBuild) {
+        let mb = read(moduleBuild);
+        if (catalog !== null) {
+            const versionKeys = [...new Set([...libs.map((l) => l.version), ...plugins.map((p) => p.version)])];
+            catalog = tomlAdd(catalog, 'versions', versionKeys.map((k) => [k === 'kotlin' ? 'kotlin' : k.replace(/[A-Z]/g, (ch) => `-${ch.toLowerCase()}`), `"${version(k)}"`]));
+            catalog = tomlAdd(catalog, 'libraries', libs.map((l) => [l.key, `{ group = "${l.coord.split(':')[0]}", name = "${l.coord.split(':')[1]}", version.ref = "${l.version === 'kotlin' ? 'kotlin' : l.version.replace(/[A-Z]/g, (ch) => `-${ch.toLowerCase()}`)}" }`]));
+            catalog = tomlAdd(catalog, 'plugins', plugins.map((p) => [p.key, `{ id = "${p.id}", version.ref = "${p.version === 'kotlin' ? 'kotlin' : p.version}" }`]));
+            files.set(catalogPath, catalog);
+            summary.push(`Update ${catalogPath}: ${libs.length} libraries and ${plugins.length} plugin${plugins.length === 1 ? '' : 's'}`);
+            mb = gradleBlockAdd(mb, 'plugins', plugins.map((p) => `alias(libs.plugins.${tomlKey(p.key)})`));
+            mb = gradleBlockAdd(mb, 'dependencies', libs.map((l) => `${l.config ?? 'implementation'}(libs.${tomlKey(l.key)})`));
+            if (rootBuild && rootBuild.endsWith('.kts')) {
+                const rb = gradleBlockAdd(read(rootBuild), 'plugins', plugins.filter((p) => p.root).map((p) => `alias(libs.plugins.${tomlKey(p.key)}) apply false`));
+                if (rb !== read(rootBuild)) {
+                    files.set(rootBuild, rb);
+                    summary.push(`Update ${rootBuild}: declare ${plugins.map((p) => p.key).join(', ')} (apply false)`);
+                }
+            }
+        }
+        else {
+            mb = gradleBlockAdd(mb, 'plugins', plugins.map((p) => `id("${p.id}") version "${version(p.version)}"`));
+            mb = gradleBlockAdd(mb, 'dependencies', libs.map((l) => `${l.config ?? 'implementation'}("${l.coord}:${version(l.version)}")`));
+        }
+        files.set(moduleBuild, mb);
+        summary.push(`Update ${moduleBuild}: plugins (${plugins.map((p) => p.key).join(', ')}) and dependencies (Retrofit, OkHttp logging, kotlinx.serialization${arch === 'retrofit-hilt' ? ', Hilt' : arch === 'retrofit-koin' ? ', Koin' : ''})`);
+    }
+    else
+        warnings.push(`No ${module}/build.gradle.kts was found; add Retrofit, the kotlinx.serialization converter and OkHttp logging yourself.`);
+    const conventions = {
+        ...c0,
+        http: 'retrofit',
+        serialization: 'kotlinx',
+        di: arch === 'retrofit-hilt' ? 'hilt' : arch === 'retrofit-koin' ? 'koin' : 'manual',
+        diFile: netFile,
+        apiFolder: `${pkgDir}/data/remote`,
+        modelsFolder: `${pkgDir}/data/model`,
+        screensFolder: c0.screensFolder || `${pkgDir}/ui/screens`,
+        baseUrl,
+    };
+    summary.push(`Save conventions: Retrofit interfaces in ${pkg}.data.remote, data classes in ${pkg}.data.model, registration with ${conventions.di}`);
+    return { files, summary, warnings, generated: [], conventions, dependenciesChanged: true };
+}