@inglorious/capacitor 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2025 Inglorious Coderz Srl.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# @inglorious/capacitor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Native project setup for [Capacitor](https://capacitorjs.com) apps, written once in `package.json` instead of clicked through Xcode and Android Studio. `@inglorious/create-app --mobile` sets it up for you.
+
+- `inglorious-capacitor configure` writes the app's native settings into `android/` and `ios/` after every `cap sync`: App Links and Universal Links, the signing team, push, Analytics off until consent, permissions and Info.plist entries, and the Firebase files.
+- `inglorious-capacitor assets` makes every icon and splash screen, light and dark, from one logo.
+
+## Installation
+
+```bash
+pnpm add -D @inglorious/capacitor
+```
+
+Run `configure` as Capacitor's `sync` hook, so `cap add` and `cap sync` both apply the settings:
+
+```json
+{
+  "scripts": {
+    "capacitor:sync:after": "inglorious-capacitor configure",
+    "mobile:init:ios": "cap add ios && inglorious-capacitor assets --ios",
+    "mobile:init:android": "cap add android && inglorious-capacitor assets --android",
+    "mobile:assets": "inglorious-capacitor assets"
+  }
+}
+```
+
+## Settings
+
+The `native` key of `package.json` holds them all. Every key is optional; the app's id comes from `capacitor.config.ts`.
+
+```json
+{
+  "native": {
+    "appLinks": {
+      "domain": "app.example.com",
+      "paths": ["/", "/jobs*"],
+      "exclude": ["#*access_token*", "/onboarding*"]
+    },
+    "ios": {
+      "teamId": "ABCDE12345",
+      "swipeBack": true,
+      "infoPlist": {
+        "ITSAppUsesNonExemptEncryption": false,
+        "NSMicrophoneUsageDescription": "Records the voice message for your job."
+      }
+    },
+    "android": {
+      "sha256": ["C1:0B:…:07"],
+      "permissions": ["android.permission.RECORD_AUDIO"]
+    },
+    "assets": {
+      "logo": "public/logo.svg",
+      "background": "#f6f3ea",
+      "backgroundDark": "#2b2b26",
+      "iconScale": 0.6,
+      "splashScale": 0.3
+    }
+  }
+}
+```
+
+### What `configure` does
+
+| Setting                                   | iOS                                                                                                        | Android                              |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| `appLinks`                                | Associated Domains entitlement                                                                             | Verified intent filter for `paths`   |
+| `appLinks` + `teamId`                     | `public/.well-known/apple-app-site-association`                                                            |                                      |
+| `appLinks` + `sha256`                     |                                                                                                            | `public/.well-known/assetlinks.json` |
+| `ios.teamId`                              | `DEVELOPMENT_TEAM`, so Xcode signs without asking                                                          |                                      |
+| `ios.swipeBack`                           | A swipe from the left edge goes back: WebKit's back gesture, turned on in a generated `MainViewController` |                                      |
+| `ios.infoPlist`                           | Info.plist entries                                                                                         |                                      |
+| `android.permissions`                     |                                                                                                            | `<uses-permission>` entries          |
+| `@capacitor-firebase/messaging` installed | Push entitlement, background mode, AppDelegate methods                                                     |                                      |
+| `@capacitor-firebase/analytics` installed | Collection off until consent                                                                               | Collection off until consent         |
+| `GoogleService-Info.plist` in the root    | Copied into the app target                                                                                 |                                      |
+| `google-services.json` in the root        |                                                                                                            | Copied to `android/app/`             |
+| always                                    |                                                                                                            | Keystores kept out of git            |
+
+Path patterns end in `*` to match a prefix: `/jobs*` is every path that starts with `/jobs`. `exclude` takes paths and, starting with `#`, fragments; only iOS can exclude, so on Android list in `paths` only what opens the app. Serve both `.well-known` files as `application/json`.
+
+It runs for the platform Capacitor is syncing, and changes nothing when the settings haven't changed. Commit `android/` and `ios/` as usual.
+
+### What `assets` does
+
+It centres the logo (`public/logo.svg` or `public/logo.png` by default) on `background` for the icons and the splash screen, and on `backgroundDark` for the dark splash screen, then hands the result to [`@capacitor/assets`](https://github.com/ionic-team/capacitor-assets) for every size and density. `iconScale` and `splashScale` are the logo's width as a share of the icon and of the splash screen. Pass `--ios` or `--android` for one platform.
+
+## License
+
+**MIT License - Free and open source**
+
+Created by [Matteo Antony Mistretta](https://github.com/IngloriousCoderz)
+
+You're free to use, modify, and distribute this software. See [LICENSE](./LICENSE) for details.

package/bin/inglorious-capacitor.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import process from "node:process"
+
+const USAGE = `Usage: inglorious-capacitor <command>
+
+  configure            Apply the "native" settings in package.json to the
+                       native projects (runs after every cap sync)
+  assets [--ios] [--android]
+                       Make the app icons and splash screens from the logo`
+
+const FIRST_ARGUMENT = 2
+const SUCCESS = 0
+const FAILURE = 1
+
+const [command, ...flags] = process.argv.slice(FIRST_ARGUMENT)
+
+try {
+  if (command === "configure") {
+    const { configure } = await import("../src/configure/index.js")
+    const platforms = await configure()
+    if (platforms.length) console.log(`Configured ${platforms.join(" and ")}`)
+  } else if (command === "assets") {
+    const { assets } = await import("../src/assets/index.js")
+    await assets({ platforms: flags.map((flag) => flag.replace(/^--/, "")) })
+  } else {
+    console.log(USAGE)
+    process.exitCode = command ? FAILURE : SUCCESS
+  }
+} catch (error) {
+  console.error(error.message)
+  process.exitCode = FAILURE
+}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@inglorious/capacitor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Configures Capacitor's native projects from package.json, and makes their icons and splash screens from one logo.",
+  "author": "Matteo Antony Mistretta <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IngloriousCoderz/inglorious-forge.git",
+    "directory": "packages/capacitor"
+  },
+  "bugs": {
+    "url": "https://github.com/IngloriousCoderz/inglorious-forge/issues"
+  },
+  "keywords": [
+    "capacitor",
+    "ios",
+    "android",
+    "app-links",
+    "icons",
+    "splash-screen",
+    "inglorious-web"
+  ],
+  "type": "module",
+  "bin": {
+    "inglorious-capacitor": "./bin/inglorious-capacitor.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "bin",
+    "src",
+    "types"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@capacitor/assets": "^4.0.0",
+    "@trapezedev/project": "^7.1.11",
+    "plist": "^3.1.1",
+    "sharp": "^0.35.5"
+  },
+  "devDependencies": {
+    "@inglorious/eslint-config": "1.2.0",
+    "prettier": "^3.9.10",
+    "vitest": "^5.1.0"
+  },
+  "engines": {
+    "node": ">= 26"
+  },
+  "scripts": {
+    "format": "prettier --write .",
+    "lint": "eslint .",
+    "test:watch": "vitest",
+    "test": "vitest run"
+  }
 }

package/src/assets/index.js

@@ -0,0 +1,127 @@
+import { execFileSync } from "node:child_process"
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs"
+import { createRequire } from "node:module"
+import path from "node:path"
+import process from "node:process"
+
+import sharp from "sharp"
+
+import { readSettings } from "../config.js"
+
+const LOGOS = ["public/logo.svg", "public/logo.png"]
+const SOURCES = path.join(
+  "node_modules",
+  ".cache",
+  "inglorious-capacitor",
+  "assets",
+)
+const PLATFORMS = ["ios", "android"]
+const DEFAULTS = {
+  background: "#ffffff",
+  backgroundDark: "#121212",
+  iconScale: 0.6,
+  splashScale: 0.3,
+}
+const ICON_SIZE = 1024
+const SPLASH_SIZE = 2732
+const TRANSPARENT = "#00000000"
+
+/**
+ * Makes every app icon and splash screen of the native projects from one
+ * logo, centred on the background colours of `native.assets` in
+ * `package.json`, in light and dark. The mark is sized from the logo itself,
+ * so a new logo needs no new settings.
+ *
+ * @param {{ root?: string, platforms?: string[] }} [options] Both platforms
+ *   that exist by default.
+ */
+export async function assets({ root = process.cwd(), platforms = [] } = {}) {
+  const settings = await readSettings(root, {})
+  const options = { ...DEFAULTS, ...settings.assets }
+  const logo =
+    options.logo ?? LOGOS.find((file) => existsSync(path.join(root, file)))
+  if (!logo || !existsSync(path.join(root, logo))) {
+    throw new Error(
+      `No logo found: add ${LOGOS.join(" or ")}, or set native.assets.logo`,
+    )
+  }
+
+  const targets = (platforms.length ? platforms : PLATFORMS).filter(
+    (platform) =>
+      PLATFORMS.includes(platform) && existsSync(path.join(root, platform)),
+  )
+  if (!targets.length) {
+    throw new Error(
+      "No native project found: run mobile:init:ios or mobile:init:android",
+    )
+  }
+
+  const sources = path.join(root, SOURCES)
+  rmSync(sources, { recursive: true, force: true })
+  mkdirSync(sources, { recursive: true })
+  await composeSources(readFileSync(path.join(root, logo)), sources, options)
+
+  execFileSync(
+    process.execPath,
+    [
+      capacitorAssetsBin(),
+      "generate",
+      ...targets.map((platform) => `--${platform}`),
+      "--assetPath",
+      SOURCES,
+    ],
+    { cwd: root, stdio: "inherit" },
+  )
+}
+
+/**
+ * The sources `@capacitor/assets` expects, so it never scales the logo itself:
+ * it would size the splash from the image's width, not the mark's.
+ */
+async function composeSources(
+  logo,
+  dir,
+  { background, backgroundDark, iconScale, splashScale },
+) {
+  const mark = (canvas, scale) =>
+    sharp(logo)
+      .resize(Math.round(canvas * scale))
+      .png()
+      .toBuffer()
+
+  const canvas = (size, color) =>
+    sharp({
+      create: { width: size, height: size, channels: 4, background: color },
+    })
+
+  const icon = await mark(ICON_SIZE, iconScale)
+  await canvas(ICON_SIZE, background)
+    .composite([{ input: icon, gravity: "centre" }])
+    .png()
+    .toFile(path.join(dir, "icon-only.png"))
+  await canvas(ICON_SIZE, TRANSPARENT)
+    .composite([{ input: icon, gravity: "centre" }])
+    .png()
+    .toFile(path.join(dir, "icon-foreground.png"))
+  await canvas(ICON_SIZE, background)
+    .png()
+    .toFile(path.join(dir, "icon-background.png"))
+
+  const splash = await mark(SPLASH_SIZE, splashScale)
+  for (const [name, color] of [
+    ["splash.png", background],
+    ["splash-dark.png", backgroundDark],
+  ]) {
+    await canvas(SPLASH_SIZE, color)
+      .composite([{ input: splash, gravity: "centre" }])
+      .png()
+      .toFile(path.join(dir, name))
+  }
+}
+
+function capacitorAssetsBin() {
+  const require = createRequire(import.meta.url)
+  const manifest = require.resolve("@capacitor/assets/package.json")
+  const { bin } = JSON.parse(readFileSync(manifest, "utf8"))
+  return path.join(path.dirname(manifest), bin["capacitor-assets"])
+}

package/src/config.js

@@ -0,0 +1,62 @@
+import { existsSync, readFileSync } from "node:fs"
+import path from "node:path"
+import process from "node:process"
+import { pathToFileURL } from "node:url"
+
+const CAPACITOR_CONFIG_FILES = [
+  "capacitor.config.ts",
+  "capacitor.config.js",
+  "capacitor.config.json",
+]
+const PUSH_PLUGIN = "@capacitor-firebase/messaging"
+const ANALYTICS_PLUGIN = "@capacitor-firebase/analytics"
+
+/**
+ * Everything `configure` and `assets` act on: the app's id and name from the
+ * Capacitor config, the `native` settings from `package.json`, and the Firebase
+ * plugins the app depends on.
+ *
+ * @param {string} root The project's folder.
+ * @param {NodeJS.ProcessEnv} [env] Capacitor hands its config to hooks here.
+ * @returns {Promise<import("../types/index.d.ts").ProjectSettings>}
+ */
+export async function readSettings(root, env = process.env) {
+  const pkg = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8"))
+  const capacitor = env.CAPACITOR_CONFIG
+    ? JSON.parse(env.CAPACITOR_CONFIG)
+    : await importCapacitorConfig(root)
+  const dependencies = { ...pkg.dependencies, ...pkg.devDependencies }
+  const native = pkg.native ?? {}
+
+  return {
+    root,
+    appId: capacitor.appId,
+    appName: capacitor.appName,
+    appLinks: native.appLinks?.domain
+      ? normalizeAppLinks(native.appLinks)
+      : null,
+    ios: { teamId: null, infoPlist: {}, ...native.ios },
+    android: { sha256: [], permissions: [], ...native.android },
+    assets: native.assets ?? {},
+    hasPush: PUSH_PLUGIN in dependencies,
+    hasAnalytics: ANALYTICS_PLUGIN in dependencies,
+  }
+}
+
+async function importCapacitorConfig(root) {
+  const file = CAPACITOR_CONFIG_FILES.map((name) => path.join(root, name)).find(
+    (candidate) => existsSync(candidate),
+  )
+  if (!file) {
+    throw new Error(`No Capacitor config found in ${root}`)
+  }
+  if (file.endsWith(".json")) {
+    return JSON.parse(readFileSync(file, "utf8"))
+  }
+  const { default: config } = await import(pathToFileURL(file).href)
+  return config
+}
+
+function normalizeAppLinks({ domain, paths = ["/*"], exclude = [] }) {
+  return { domain, paths, exclude }
+}

package/src/configure/android.js

@@ -0,0 +1,96 @@
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import { intentFilterData } from "./well-known.js"
+
+const ACTIVITY = "manifest/application/activity"
+const APPLICATION = "manifest/application"
+const MANIFEST = "manifest"
+const APP_LINKS_FILTER = `${ACTIVITY}/intent-filter[@android:autoVerify='true']`
+const ANALYTICS_OFF = [
+  "firebase_analytics_collection_enabled",
+  "google_analytics_adid_collection_enabled",
+]
+const GOOGLE_SERVICES = "google-services.json"
+const KEYSTORES = ["*.jks", "*.keystore"]
+
+/**
+ * Applies the settings to the Android project: App Links, Analytics off until
+ * consent, extra permissions, the Firebase file, and keystores kept out of git.
+ *
+ * @param {import("@trapezedev/project").MobileProject} project
+ * @param {import("../../types/index.d.ts").ProjectSettings} settings
+ */
+export function configureAndroid(project, settings) {
+  const manifest = project.android.getAndroidManifest()
+  const androidRoot = path.join(settings.root, "android")
+
+  if (manifest.find(APP_LINKS_FILTER)?.length) {
+    manifest.deleteNodes(APP_LINKS_FILTER)
+  }
+  if (settings.appLinks) {
+    manifest.injectFragment(ACTIVITY, appLinksFilter(settings.appLinks))
+  }
+
+  if (settings.hasAnalytics) {
+    for (const name of ANALYTICS_OFF) {
+      if (
+        manifest.find(`${APPLICATION}/meta-data[@android:name='${name}']`)
+          ?.length
+      ) {
+        continue
+      }
+      manifest.injectFragment(
+        APPLICATION,
+        `<meta-data android:name="${name}" android:value="false" />`,
+      )
+    }
+  }
+
+  for (const permission of settings.android.permissions) {
+    if (
+      manifest.find(
+        `${MANIFEST}/uses-permission[@android:name='${permission}']`,
+      )?.length
+    ) {
+      continue
+    }
+    manifest.injectFragment(
+      MANIFEST,
+      `<uses-permission android:name="${permission}" />`,
+    )
+  }
+
+  const googleServices = path.join(settings.root, GOOGLE_SERVICES)
+  if (existsSync(googleServices)) {
+    copyFileSync(googleServices, path.join(androidRoot, "app", GOOGLE_SERVICES))
+  }
+
+  ignoreKeystores(path.join(androidRoot, ".gitignore"))
+}
+
+function appLinksFilter(appLinks) {
+  const data = intentFilterData(appLinks)
+    .map(
+      (attributes) =>
+        `<data ${Object.entries(attributes)
+          .map(([name, value]) => `${name}="${value}"`)
+          .join(" ")} />`,
+    )
+    .join("")
+
+  return `<intent-filter android:autoVerify="true"><action android:name="android.intent.action.VIEW" /><category android:name="android.intent.category.DEFAULT" /><category android:name="android.intent.category.BROWSABLE" />${data}</intent-filter>`
+}
+
+function ignoreKeystores(file) {
+  if (!existsSync(file)) return
+
+  const source = readFileSync(file, "utf8")
+  const lines = source.split("\n").map((line) => {
+    const uncommented = line.replace(/^#/, "")
+    return KEYSTORES.includes(uncommented) ? uncommented : line
+  })
+  const missing = KEYSTORES.filter((pattern) => !lines.includes(pattern))
+  const next = [...lines, ...missing].join("\n")
+  if (next !== source) writeFileSync(file, next)
+}