@hyodotdev/openiap 0.0.0-bootstrap.0 → 0.1.0

package/src/doctor.mjs

@@ -0,0 +1,183 @@
+import {
+  clientFiles,
+  dependencies,
+  detectFramework,
+  hasUnreadablePath,
+  isEnvFile,
+  isDirectory,
+  isGeneratedDir,
+  listDir,
+  manifestIsMalformed,
+  read,
+  unreadable,
+} from "./project.mjs";
+export { FINDING_IDS } from "./findings.mjs";
+import { finding } from "./findings.mjs";
+
+import {
+  DOTENV_PACKAGES,
+  androidStoreChecks,
+  baseUrlChecks,
+  envNameChecks,
+  iosSceneChecks,
+  secretKeyChecks,
+} from "./checks.mjs";
+
+/**
+ * Everything here reads the checkout and nothing else. A device, a store
+ * account, and the network can each break an integration in ways no file
+ * records, so those are reported as unchecked rather than guessed at.
+ */
+const NOT_CHECKED_LOCALLY = [
+  "Store account state: agreements, product status, and license testers.",
+  "Device state: a scene session or an installed build left by another app that shares the bundle id.",
+  "Play billing availability on the device and its signed-in account.",
+];
+
+/** What this run did not look at, so "no problems found" is not read as more. */
+function skippedChecks(root, framework) {
+  const skipped = [];
+  const androidFiles = listDir(root, "android");
+  const hasAndroid =
+    androidFiles.includes("gradle.properties") ||
+    listDir(root, "android/app").some((one) =>
+      ["build.gradle", "build.gradle.kts"].includes(one),
+    );
+  if (
+    !hasAndroid &&
+    !unreadable.has("android") &&
+    !unreadable.has("android/app")
+  ) {
+    skipped.push("Android store flavor: no android/ project was found here.");
+  }
+
+  const iosDirs = listDir(root, "ios").filter((one) =>
+    !isGeneratedDir(one) && isDirectory(root, `ios/${one}`),
+  );
+  const iosPlists = [
+    "ios/Info.plist",
+    ...iosDirs.map((one) => `ios/${one}/Info.plist`),
+  ];
+  const iosPlist = iosPlists.some((file) => read(root, file) !== null);
+  if (framework !== "expo" && framework !== "react-native") {
+    skipped.push(`iOS scene delegate: not checked for ${framework} projects.`);
+  } else if (!iosPlist && !hasUnreadablePath("ios")) {
+    skipped.push("iOS scene delegate: no ios/ Info.plist was found here.");
+  }
+
+  // The unexpected-prefix half runs for every framework except `unknown`.
+  const deps = dependencies(root);
+  if (DOTENV_PACKAGES.some((one) => deps[one])) {
+    skipped.push(
+      "Env variable names: a dotenv transform is installed, so neither prefix rule applies.",
+    );
+  } else if (framework === "unknown") {
+    skipped.push(
+      "Env variable names: no framework was detected, so neither prefix rule applies.",
+    );
+  }
+
+  const files = clientFiles(root);
+  if (files.length === 0) {
+    skipped.push(
+      "Keys and base URL: no env file or app config was found here.",
+    );
+  } else if (!files.some((one) => isEnvFile(one))) {
+    skipped.push(
+      "Base URL: only env files are read for it, and there is none here.",
+    );
+  }
+  // Saying which files are read is the only way "no problems" is not read as a
+  // verdict on the ones that are not.
+  skipped.push(
+    "Application source: keys are looked for in env files, app.config, app.json and eas.json only.",
+  );
+  return skipped;
+}
+
+function summarize(framework, findings, skipped = []) {
+  const errors = findings.filter((one) => one.level === "error").length;
+  return {
+    framework,
+    findings,
+    errors,
+    warnings: findings.length - errors,
+    notCheckedLocally: [...NOT_CHECKED_LOCALLY, ...skipped],
+  };
+}
+
+export function doctor(root) {
+  // Reporting a path it never read as clean is the one answer this must never
+  // give, so a missing or unreadable project is a finding, not silence.
+  if (!isDirectory(root, ".")) {
+    return summarize("unknown", [
+      finding(
+        "project-not-a-directory",
+        "error",
+        root,
+        "This path is not a directory that could be read.",
+        "Pass the root of the app you want checked.",
+      ),
+    ]);
+  }
+
+  unreadable.clear();
+  const framework = detectFramework(root);
+  const findings = [];
+  if (manifestIsMalformed(root)) {
+    // Framework detection reads this file, so every check below it is
+    // degraded. Saying so beats reporting the leftovers as a clean bill.
+    findings.push(
+      finding(
+        "project-manifest-unreadable",
+        "error",
+        "package.json",
+        "package.json exists but is not valid JSON, so nothing could be read from it.",
+        "Fix the JSON; framework detection and its checks depend on it.",
+      ),
+    );
+  }
+  findings.push(
+    ...androidStoreChecks(root),
+    ...secretKeyChecks(root, framework),
+    ...envNameChecks(root, framework),
+    ...baseUrlChecks(root, framework),
+    ...iosSceneChecks(root, framework),
+  );
+  // Compute this first: it is the only reader of some directories, and their
+  // misses have to reach the drain below.
+  const skipped = skippedChecks(root, framework);
+  for (const file of [...unreadable].sort()) {
+    findings.push(
+      finding(
+        "project-file-unreadable",
+        "error",
+        file,
+        `This path could not be read, so nothing in it was checked: ${file}`,
+        "Fix its permissions or its type; a socket, a FIFO and a dangling symlink are not readable.",
+      ),
+    );
+  }
+  return summarize(framework, findings, skipped);
+}
+
+export function formatText(result) {
+  const lines = [`Framework: ${result.framework}`];
+  if (result.findings.length === 0) {
+    lines.push("", "No problems found in this checkout.");
+  } else {
+    lines.push("");
+    for (const one of result.findings) {
+      const where = one.line ? `${one.file}:${one.line}` : one.file;
+      lines.push(`${one.level === "error" ? "error" : "warn "}  ${where}`);
+      lines.push(`       ${one.message}`);
+      lines.push(`       ${one.fix}`);
+      lines.push(`       [${one.id}]`);
+      lines.push("");
+    }
+    lines.push(`${result.errors} error(s), ${result.warnings} warning(s).`);
+  }
+  lines.push("", "Not checked locally:");
+  for (const item of result.notCheckedLocally) lines.push(`  - ${item}`);
+  return lines.join("\n");
+}

package/src/findings.mjs

@@ -0,0 +1,33 @@
+/**
+ * Every id this tool can emit. Agents are told to match on `id`, so a rename
+ * is a contract change: the registry test fails until this list and the README
+ * agree with the code.
+ */
+export const FINDING_IDS = Object.freeze([
+  "android-store-flavor-conflict",
+  "android-store-flavor-mismatch",
+  "android-store-not-play",
+  "android-horizon-app-id-missing",
+  "iapkit-secret-key-in-client",
+  "iapkit-secret-key-in-env",
+  "iapkit-secret-key-in-config",
+  "iapkit-env-missing-expo-prefix",
+  "iapkit-env-unexpected-expo-prefix",
+  "iapkit-base-url-invalid",
+  "iapkit-base-url-scheme",
+  "iapkit-base-url-has-path",
+  "ios-scene-delegate-missing",
+  "project-file-unreadable",
+  "project-manifest-unreadable",
+  "project-not-a-directory",
+]);
+
+/**
+ * Every finding carries a stable id so an agent can act on it without parsing
+ * prose, and names the file it was read from so a person can verify it.
+ */
+export function finding(id, level, file, message, fix, extra = {}) {
+  if (!FINDING_IDS.includes(id))
+    throw new Error(`Unregistered finding id: ${id}`);
+  return { id, level, file, message, fix, ...extra };
+}

package/src/init.mjs

@@ -0,0 +1,95 @@
+import { readdirSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { detectFramework } from "./project.mjs";
+
+const DOCS = "https://openiap.dev";
+
+export const ROLES = [
+  {
+    id: "app",
+    label: "App — connect purchases to access",
+    guide: "/docs/guides/ai-assistants",
+  },
+  {
+    id: "experience",
+    label: "Experience — connect a paywall or experiment",
+    guide: "/commerce-protocol/ecosystem#experience",
+  },
+  {
+    id: "commerce",
+    label: "Commerce — provide verification and access",
+    guide: "/commerce-protocol/implementation",
+  },
+  {
+    id: "data",
+    label: "Data — receive events for analytics or automation",
+    guide: "/commerce-protocol/getting-started#receive-events",
+  },
+];
+
+export async function chooseRole() {
+  if (!process.stdin.isTTY || !process.stderr.isTTY) {
+    throw new Error(
+      "Choose a role with --role app|experience|commerce|data, or run openiap in a terminal.",
+    );
+  }
+  const prompt = createInterface({
+    input: process.stdin,
+    output: process.stderr,
+  });
+  const controller = new AbortController();
+  prompt.once("close", () => controller.abort());
+  try {
+    process.stderr.write(
+      `\nWhat does your product do?\n\n${ROLES.map((role, index) => `  ${index + 1}. ${role.label}`).join("\n")}\n\n`,
+    );
+    const answer = (
+      await prompt.question("Choose a number or role: ", {
+        signal: controller.signal,
+      })
+    ).trim();
+    return (
+      ROLES.find(
+        (role, index) => role.id === answer || String(index + 1) === answer,
+      )?.id ?? answer
+    );
+  } catch (error) {
+    if (error.name === "AbortError")
+      throw new Error("Role selection canceled.");
+    throw error;
+  } finally {
+    prompt.close();
+  }
+}
+
+/** A local starting brief; the linked guides own implementation requirements. */
+export function implementationBrief(root, roleId) {
+  const role = ROLES.find((candidate) => candidate.id === roleId);
+  if (!role)
+    throw new Error(
+      `Unknown role: ${roleId}. Choose app, experience, commerce, or data.`,
+    );
+  try {
+    readdirSync(root);
+  } catch {
+    throw new Error(`Cannot read project directory: ${root}`);
+  }
+  const framework = detectFramework(root);
+  return `# OpenIAP implementation brief
+
+Paste this into your coding assistant in the project below.
+
+Project path (data): ${JSON.stringify(root)}
+Role: ${role.label}
+Framework hint: ${framework === "unknown" ? "not detected; inspect the project" : `${framework}; confirm the target app`}
+Desired outcome: [describe one thing your customer should be able to do]
+
+Read the project instructions and inspect the existing stack. Keep its login, product model, and services. Ask me to choose missing stores, products, service providers, and ownership policies before implementing those choices.
+
+Read ${DOCS}${role.guide} and the references it links for this role. If a reference is unavailable, ask for its contents; do not guess the contract. Use Client Protocol for app purchase APIs and Commerce Protocol for backend connections. Use the supported capabilities of my chosen services; no particular backend is required.
+
+Implement the smallest working connection for my role. Keep credentials on their intended side of the app/backend boundary. Follow the role's implementation and conformance requirements, including failure and recovery. Do not claim another role merely because this product connects to it.
+
+Run the result from clean source. Show the customer outcome, the commands and actual test results, and any remaining product or deployment decisions. Distinguish local fixtures from real store sandbox evidence. Keep changes uncommitted for review.
+`;
+}