novahiz 0.1.0 → 0.2.2

package/adapters/opencode/instructions.md

@@ -2,11 +2,11 @@
 
 ## Obsidian Memory
 
-Obsidian (`C:\Users\hiz\Documents\novahiz`) is the user's second memory.
+Obsidian (`C:\Users\hiz\Documents\Novahiz`) is the user's second memory.
 
 ### Rules
 1. When the user asks to **save / memorize / update obsidian memory**, load the `memory-save` skill and follow its procedure without exception.
-2. Determine the target folder **only** from the `novahiz\_meta\routing.md` table (source of truth). Never guess. When ambiguous, ask the user.
+2. Determine the target folder **only** from the `Novahiz\_meta\routing.md` table (source of truth). Never guess. When ambiguous, ask the user.
 3. Display the chosen path before writing.
 4. Never write to `index.md`, `log.md`, `hot.md`, `.manifest.json`, `_meta/`, or `.obsidian/` **except through a dedicated maintenance skill** (wiki-ingest/wiki-lint/wiki-status for index/log/hot/manifest; graph-colorize for `.obsidian/graph.json`, with mandatory backup). The `memory-save` skill writes only to the targeted content page.
 5. Never create a root folder on your own. Every new category requires user agreement and an update to `routing.md`.
@@ -28,26 +28,15 @@ Playwright uses a **persistent profile** that preserves data across sessions (co
 
 ## Behavioral & Quality Rules
 
-1. **Mandatory humanizer on text and code** — On every code or text modification, load the `humanizer` skill and apply its rules (remove AI writing tics: not-X-but-Y contrasts, forced triads, excessive dashes, empty phrases, marketing jargon). **Exception:** `humanizer` applies only to frontend text (titles, paragraphs, interface copy) or AI pattern audits — never to browser navigation/research tasks. Browser tasks (navigation, search, extraction) proceed as direct actions without a roadmap.
-2. **Mandatory impeccable on design** — On every design modification (UI, page, component, style, layout, motion, interface copy), load the `impeccable` skill and follow its workflow (setup then the appropriate command: `polish`, `audit`, `critique`, `animate`, etc.).
-3. **Impeccable / /impeccable live — NEVER use sub-agents** — The `impeccable` skill, the `/impeccable live` command, and any use of impeccable skills must **never** start in sub-agent mode, **ever**, even if the task seems suitable (distributed analysis, multiple variants, multi-surface audit). **Single exception:** only when the user explicitly requests launching a sub-agent ("launch a sub-agent", "use a sub-agent", etc.). The main agent always retains the interactive session and browser context.
-4. **Supabase** — On any Supabase task (database, auth, RLS, Edge Functions, migrations, Storage, Realtime, CLI/MCP), load the `supabase` and `supabase-postgres-best-practices` skills before acting.
+1. **Mandatory humanizer on text and code** — On every code or text modification meant for a reader, load the `novahiz-humanizer` skill and apply its rules (remove AI writing tics: not-X-but-Y contrasts, forced triads, excessive dashes, empty phrases, marketing jargon). Browser tasks (navigation, search, extraction) proceed as direct actions without a roadmap.
+2. **Supabase** — On any Supabase task (database, auth, RLS, Edge Functions, migrations, Storage, Realtime, CLI/MCP), load the `novahiz-supabase` and `novahiz-postgres` skills before acting.
 5. **Honesty and critical thinking** — Always be honest. Avoid false good ideas. Maintain critical thinking. **Zero simulation objective:** never claim to have executed, tested, or verified what was not. Explicitly report uncertainties and assumptions.
 6. **Propose next steps** — After completing a task, always honestly propose the relevant next step. Do not invent unnecessary work or mask failures.
 7. **Challenge the request** — Take the initiative to question the user's request when it is inconsistent, ambiguous, risky, or suboptimal. Explain why and propose an alternative.
 8. **Architecture quality** — Always adopt a modular, scalable, and maintainable approach. Never sacrifice quality for speed.
 9. **Todo list in real time** — Keep the todo list updated throughout the task: move a step to `in_progress` before starting it, mark it `completed` once verified, and add steps discovered along the way. No frozen lists or batch completion at the end.
 
-## Design Rules — Impeccable
-
-### Workflow per operation type
-
-| Operation | Mandatory command | When |
-|-----------|------------------|------|
-| **Create** a design | `/impeccable shape` | At the start, to establish the initial shape |
-| **Fix / Repair** a design | `impeccable audit` + `/impeccable critique` | Before and after the fix |
-| **Improve** a design | `/impeccable polish` | To refine and elevate |
-| **Verify** after a major task | `/impeccable critique` (+ `impeccable audit` if needed) | At the end of any significant design task |
+## Design Rules
 
 ### Absolute rule — AI patterns
 

package/adapters/opencode/novahiz.ts

@@ -1,9 +1,73 @@
 import type { Plugin } from "@opencode-ai/plugin";
 import { spawnSync } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+// Inlined from src/prompt-rewriter.ts to avoid broken relative path in installed plugin
+type RewriteResult = { original: string; rewritten: string; sourceLanguage: string; wasRewritten: boolean };
+
+function detectLanguage(prompt: string): string {
+  if (/[\u0600-\u06FF]/.test(prompt)) return "ar";
+  return "en";
+}
+
+const AR_EN: Array<[RegExp, string]> = [
+  [/اصلاح|اصلح/g, "fix"], [/انشاء|اصنع/g, "create"], [/اضافة|اضف/g, "add"],
+  [/حذف|احذف/g, "remove"], [/تعديل|عدّل/g, "modify"], [/هاكود|اكتشف/g, "debug"],
+  [/اختبار|اختبر/g, "test"], [/ترحيل|هجر/g, "migrate"], [/اضبط|ضبط/g, "configure"],
+  [/تحسين|حسّن/g, "optimize"], [/تبسيط|بسّط/g, "simplify"], [/تنظيف|نظّف/g, "clean up"],
+  [/تنفيذ|طبّق/g, "implement"], [/استخدام|استخدم/g, "use"], [/استبدال|بدّل/g, "replace"],
+  [/كتابة|اكتب/g, "write"], [/قراءة|اقرأ/g, "read"], [/حفظ|احفظ/g, "save"],
+  [/عرض|اعرض/g, "display"], [/اخفاء|اخفي/g, "hide"], [/تفعيل|فعّل/g, "enable"],
+  [/تعطيل|عطّل/g, "disable"], [/دالة/g, "function"], [/فئة/g, "class"],
+  [/طريقة/g, "method"], [/متغير/g, "variable"], [/ملف/g, "file"], [/شفرة/g, "code"],
+  [/مشكلة/g, "issue"], [/حل/g, "solution"], [/كيف/g, "how to"], [/لماذا/g, "why"],
+  [/أي/g, "which"], [/افعل/g, "do"], [/في/g, "in"], [/من/g, "from"], [/على/g, "on"],
+  [/صفحة/g, "page"], [/هبوط/g, "landing"], [/متجاوبة/g, "responsive"],
+  [/تصميم/g, "design"], [/واجهة/g, "interface"], [/زر/g, "button"], [/قائمة/g, "menu"],
+  [/شريط/g, "bar"], [/نافذة/g, "window"], [/شكل/g, "form"],
+  [/الخادم|السيرفر/g, "server"], [/قاعدة البيانات/g, "database"],
+  [/صفحة الهبوط/g, "landing page"], [/المصادقة/g, "auth"],
+  [/تسجيل الدخول/g, "login"], [/خطأ/g, "bug"], [/اداء/g, "performance"], [/امان/g, "security"],
+];
+
+function rewritePrompt(prompt: string): RewriteResult {
+  const sourceLanguage = detectLanguage(prompt);
+  if (sourceLanguage === "en") {
+    let r = prompt.trim().replace(/^I\s+want\s+to\s+/i, "").replace(/^I\s+need\s+to\s+/i, "")
+      .replace(/^Can\s+you\s+/i, "").replace(/^Could\s+you\s+/i, "").replace(/^Please\s+/i, "")
+      .replace(/^I\s+would\s+like\s+to\s+/i, "").replace(/^It\s+would\s+be\s+great\s+if\s+you\s+could\s+/i, "")
+      .replace(/[.!?]+$/, "").trim();
+    return { original: prompt, rewritten: r, sourceLanguage, wasRewritten: r !== prompt };
+  }
+  let result = prompt;
+  for (const [pattern, replacement] of AR_EN) result = result.replace(pattern, replacement);
+  let r = result.trim().replace(/^I\s+want\s+to\s+/i, "").replace(/^I\s+need\s+to\s+/i, "")
+    .replace(/^Can\s+you\s+/i, "").replace(/^Could\s+you\s+/i, "").replace(/^Please\s+/i, "")
+    .replace(/^I\s+would\s+like\s+to\s+/i, "").replace(/^It\s+would\s+be\s+great\s+if\s+you\s+could\s+/i, "")
+    .replace(/[.!?]+$/, "").trim();
+  return { original: prompt, rewritten: r, sourceLanguage, wasRewritten: true };
+}
+
+function ensureProjectMemory(cwd: string): boolean {
+  try {
+    const root = join(cwd, "project-memory");
+    const slots = join(root, "slots");
+    const index = join(root, "index.json");
+    if (!existsSync(root)) mkdirSync(root, { recursive: true });
+    if (!existsSync(slots)) mkdirSync(slots, { recursive: true });
+    if (!existsSync(index)) {
+      const empty = { version: 1, updated: new Date().toISOString(), slots: [] };
+      writeFileSync(index, `${JSON.stringify(empty, null, 2)}\n`, "utf8");
+      return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
 const HOME =
   process.env.NOVAHIZ_HOME && process.env.NOVAHIZ_HOME.length > 0
     ? process.env.NOVAHIZ_HOME
@@ -28,8 +92,10 @@ function readConfig(): NovahizConfig {
 
 const CONFIG = readConfig();
 const GATE = CONFIG.gate ?? {};
-const ENV_ESCAPE = typeof GATE.envEscape === "string" && GATE.envEscape.length > 0 ? GATE.envEscape : "NOVAHIZ_GATE";
-const ESCAPE = (process.env[ENV_ESCAPE] || "").toLowerCase();
+// H1: envEscape is NOT configurable — a writable config must not be able to
+// redirect the kill-switch to an unrelated variable (e.g. CI=false).
+// Single escape hatch name after brand rename.
+const ESCAPE = (process.env.NOVAHIZ_GATE ?? "").toLowerCase();
 // gate.enabled=false disables the plugin the same way the CLI gate does (see src/commands/gate.ts).
 // gate.mode (block/warn/audit) stays owned by the CLI: the plugin only forwards the gate exit code.
 const DISABLED =
@@ -40,9 +106,30 @@ const GATE_TOOLS = new Set(
 
 type RunResult = { status: number; stdout: string; stderr: string; spawnError?: string };
 
+// C1: timeout prevents a hung CLI from freezing the whole OpenCode process.
+// C2: maxBuffer caps output; oversized output is treated as a gate failure,
+// never as truncated-then-allowed.
+const RUN_TIMEOUT_MS = 10_000;
+const RUN_MAX_BUFFER = 1_048_576;
+
 function run(args: string[], input?: string): RunResult {
-  const result = spawnSync(NODE, [CLI, ...args], { encoding: "utf8", input });
+  // C1: On Windows, SIGTERM is emulated via process.kill() which sends
+  //TerminateProcess + exit code 1, causing the CLI to report status 1 instead
+  //of being properly terminated. Use SIGKILL on Windows (unavoidable but at
+  //least doesn't pretend graceful shutdown is possible).
+  const isWin = process.platform === "win32";
+  const result = spawnSync(NODE, [CLI, ...args], {
+    encoding: "utf8",
+    input,
+    timeout: RUN_TIMEOUT_MS,
+    maxBuffer: RUN_MAX_BUFFER,
+    killSignal: isWin ? "SIGKILL" : "SIGTERM"
+  });
   if (result.error) return { status: 1, stdout: "", stderr: "", spawnError: result.error.message };
+  // On Windows, timeout-killed processes always exit with status 1 (TerminateProcess).
+  // The `signal` property is set when the process was killed by a signal.
+  const timedOut = result.status === 1 && !result.stdout?.trim() && Boolean(result.signal);
+  if (timedOut) return { status: 1, stdout: "", stderr: "Novahiz timed out" };
   return { status: result.status ?? 1, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
 }
 
@@ -56,6 +143,12 @@ function textFromParts(parts: unknown): string {
   return chunks.join("\n").trim();
 }
 
+// H2: Session IDs must be non-empty strings. This guards against undefined/null
+// being passed to spawnSync env, which would throw on Windows.
+function isValidSessionId(id: unknown): id is string {
+  return typeof id === "string" && id.trim().length > 0;
+}
+
 export const NovahizPlugin: Plugin = async ({ client }) => {
   const loadedBySession = new Map<string, Set<string>>();
   const categoriesBySession = new Map<string, string[]>();
@@ -65,7 +158,7 @@ export const NovahizPlugin: Plugin = async ({ client }) => {
 
   const log = async (level: "info" | "warn", message: string): Promise<void> => {
     try {
-      await client.app.log({ body: { service: "novahiz", level, message } });
+      await client.app.log({ body: { service: "Novahiz", level, message } });
     } catch {
       return;
     }
@@ -79,10 +172,9 @@ export const NovahizPlugin: Plugin = async ({ client }) => {
   };
 
   // Sessions only vanish from memory on session.deleted, which may never arrive.
-  // Prune entries idle for longer than SESSION_TTL_MS once the map grows.
+  // Prune entries idle for longer than SESSION_TTL_MS on every access.
   const touch = (sessionID: string): void => {
     lastSeenBySession.set(sessionID, Date.now());
-    if (lastSeenBySession.size < 50) return;
     const cutoff = Date.now() - SESSION_TTL_MS;
     for (const [id, seen] of lastSeenBySession) {
       if (seen < cutoff) forget(id);
@@ -94,6 +186,8 @@ export const NovahizPlugin: Plugin = async ({ client }) => {
 
   return {
     config: async (input) => {
+      ensureProjectMemory(process.cwd());
+      if (DISABLED) return;
       try {
         const config = input as { mcp?: Record<string, unknown> };
         if (!config.mcp) config.mcp = {};
@@ -132,11 +226,23 @@ export const NovahizPlugin: Plugin = async ({ client }) => {
     },
 
     "chat.message": async (input, output) => {
+      ensureProjectMemory(process.cwd());
+      if (DISABLED) return;
       try {
+        if (!isValidSessionId(input.sessionID)) return;
         touch(input.sessionID);
         const text = textFromParts(output.parts);
         if (text.length === 0) return;
-        const result = run(["classify", text]);
+
+        // Prompt rewriter: translate non-English prompts to optimized English
+        // before classification. Responses always match the user's language.
+        const rewrite = rewritePrompt(text);
+        const classifyText = rewrite.rewritten;
+        if (rewrite.wasRewritten) {
+          await log("info", `Prompt rewritten: ${rewrite.sourceLanguage} → English ("${classifyText.slice(0, 80)}")`);
+        }
+
+        const result = run(["classify", classifyText]);
         if (result.status !== 0) {
           await log("warn", `Classify failed (exit ${result.status}), no enforcement injected: ${result.stderr.trim().slice(0, 200)}`);
           return;
@@ -155,6 +261,12 @@ export const NovahizPlugin: Plugin = async ({ client }) => {
           await log("warn", "Classify returned invalid JSON, no enforcement injected");
           return;
         }
+        // M5: the `as` cast is compile-time only — validate the shape at runtime
+        // so a malformed classify response cannot silently disable enforcement.
+        if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.categories)) {
+          await log("warn", "Classify returned unexpected structure, no enforcement injected");
+          return;
+        }
         const categories = (parsed.categories ?? []).map((entry) => entry.id);
         categoriesBySession.set(input.sessionID, categories);
         const primary = parsed.primary ?? categories[0] ?? null;
@@ -165,8 +277,11 @@ export const NovahizPlugin: Plugin = async ({ client }) => {
         const providers = parsed.providers ?? [];
         const lines = [
           "[Novahiz enforcement]",
-          `Categories detectees: ${categories.join(", ") || "aucune"}${primary ? ` (primaire: ${primary})` : ""}`
+          `Categories detected: ${categories.join(", ") || "none"}${primary ? ` (primary: ${primary})` : ""}`
         ];
+        if (rewrite.wasRewritten) {
+          lines.push(`User language: ${rewrite.sourceLanguage} — respond in this language, not English.`);
+        }
         if (roadmap) {
           lines.push(`Roadmap ${roadmap.id}:`);
           roadmap.steps.forEach((step, index) => {
@@ -174,9 +289,9 @@ export const NovahizPlugin: Plugin = async ({ client }) => {
             lines.push(`  ${index + 1}. [${step.kind}] ${step.label}${skills}`);
           });
         }
-        if (enforced.length > 0) lines.push(`Skills requis (roadmap): ${enforced.join(", ")}`);
-        if (suggested.length > 0) lines.push(`Skills suggeres: ${suggested.join(", ")}`);
-        if (providers.length > 0) lines.push(`Outils pour cette tache: ${providers.join(", ")}`);
+        if (enforced.length > 0) lines.push(`Required skills (roadmap): ${enforced.join(", ")}`);
+        if (suggested.length > 0) lines.push(`Suggested skills: ${suggested.join(", ")}`);
+        if (providers.length > 0) lines.push(`Tools for this task: ${providers.join(", ")}`);
         const ledger = run(["task", "current", "--session", input.sessionID]);
         if (ledger.status === 0 && ledger.stdout.trim().length > 0) {
           try {
@@ -186,9 +301,10 @@ export const NovahizPlugin: Plugin = async ({ client }) => {
             await log("warn", "Ledger state is invalid JSON, enforcement injected without the task summary");
           }
         }
-        lines.push("Le gate bloque edit/write/patch/apply_patch/bash/shell tant que les skills requis ne sont pas charges via skill({name:\"...\"}).");
-        lines.push("Le gate est sensible au contenu: humanizer pour la prose, impeccable pour le style.");
-        lines.push("Config editee = redemarrage d'opencode requis (config lue a l'import).");
+        lines.push("The gate blocks edit/write/patch/apply_patch/bash/shell until the required skills are loaded via skill({name:\"...\"}).");
+        lines.push("The gate is content-aware: novahiz-humanizer for prose; design files take no style gate rule.");
+        lines.push("Config edited = opencode restart required (config read at import).");
+        lines.push("Memory lives in project-memory/ under the project root (cwd): index.json + fixed-size slots (8000 chars / 200 lines) with compact → archive → new-slot rotation. Use the MCP memory_* tools to read and append.");
         enforcementBySession.set(input.sessionID, lines.join("\n"));
       } catch (error) {
         await log("warn", `chat.message hook failed, no enforcement injected: ${String(error).slice(0, 200)}`);
@@ -198,14 +314,21 @@ export const NovahizPlugin: Plugin = async ({ client }) => {
 
     "experimental.chat.system.transform": async (input, output) => {
       if (DISABLED) return;
-      const sessionID = input.sessionID;
-      if (!sessionID) return;
-      const block = enforcementBySession.get(sessionID);
-      if (block) output.system.push(block);
+      try {
+        const sessionID = input.sessionID;
+        if (!sessionID) return;
+        const block = enforcementBySession.get(sessionID);
+        if (block) output.system.push(block);
+      } catch (error) {
+        await log("warn", `system.transform hook failed: ${String(error).slice(0, 200)}`);
+      }
     },
 
     "tool.execute.before": async (input, output) => {
       try {
+        // H-Plugin: validate session ID before using it — prevents undefined/null
+        // from being passed to spawnSync env (throws on Windows).
+        if (!isValidSessionId(input.sessionID)) return;
         touch(input.sessionID);
         if (!loadedBySession.has(input.sessionID)) loadedBySession.set(input.sessionID, new Set());
         const loaded = loadedBySession.get(input.sessionID)!;
@@ -215,7 +338,12 @@ export const NovahizPlugin: Plugin = async ({ client }) => {
           const name = args?.name ?? args?.skill;
           if (name) {
             loaded.add(String(name));
-            run(["session-load", "--session", input.sessionID, "--skill", String(name)]);
+            // H3: surface session-load failures — otherwise the gate blocks later
+            // with no trace of why the skill was never recorded.
+            const loadResult = run(["session-load", "--session", input.sessionID, "--skill", String(name)]);
+            if (loadResult.status !== 0) {
+              await log("warn", `session-load failed for skill ${name}: ${(loadResult.stderr || "").trim().slice(0, 200)}`);
+            }
           }
           return;
         }
@@ -245,9 +373,13 @@ export const NovahizPlugin: Plugin = async ({ client }) => {
           })()
         );
 
+        // H2: fail-closed — an unavailable gate denies the tool call instead of
+        // silently bypassing enforcement. NOVAHIZ_GATE=off remains the escape hatch.
         if (result.spawnError) {
-          await log("warn", `Gate unavailable, allowing the tool call: ${result.spawnError}`);
-          return;
+          await log("warn", `Gate unavailable, denying the tool call: ${result.spawnError}`);
+          throw new Error(
+            `Novahiz gate blocked ${input.tool}: gate unavailable (${result.spawnError}). Fix the install (run sync, check catalog/) or set NOVAHIZ_GATE=off to disable.`
+          );
         }
         if (result.status === 2) {
           throw new Error(`Novahiz gate blocked ${input.tool}.\n${result.stdout}`);
@@ -259,7 +391,9 @@ export const NovahizPlugin: Plugin = async ({ client }) => {
         }
       } catch (error) {
         if (error instanceof Error && error.message.startsWith("Novahiz gate")) throw error;
-        await log("warn", `Gate error, allowing the tool call: ${String(error)}`);
+        // H2: fail-closed — unknown gate errors deny, they never bypass.
+        await log("warn", `Gate error, denying the tool call as precaution: ${String(error)}`);
+        throw new Error(`Novahiz gate blocked ${input.tool}: internal gate error. Set NOVAHIZ_GATE=off to disable.`);
       }
     }
   };

package/bundled-skills/{skill-creator/LICENSE.txt → android-reverse-engineering/LICENSE}

@@ -1,4 +1,3 @@
-
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -49,7 +48,7 @@
       "Contribution" shall mean any work of authorship, including
       the original version of the Work and any modifications or additions
       to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
+      submitted to the Licensor for inclusion in the Work by the copyright owner
       or by an individual or Legal Entity authorized to submit on behalf of
       the copyright owner. For the purposes of this definition, "submitted"
       means any form of electronic, verbal, or written communication sent
@@ -61,7 +60,7 @@
       designated in writing by the copyright owner as "Not a Contribution."
 
       "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
+      on behalf of whom a Contribution has been received by the Licensor and
       subsequently incorporated within the Work.
 
    2. Grant of Copyright License. Subject to the terms and conditions of
@@ -107,7 +106,7 @@
       (d) If the Work includes a "NOTICE" text file as part of its
           distribution, then any Derivative Works that You distribute must
           include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
+          within such NOTICE file, excluding any notices that do not
           pertain to any part of the Derivative Works, in at least one
           of the following places: within a NOTICE text file distributed
           as part of the Derivative Works; within the Source form or
@@ -176,18 +175,7 @@
 
    END OF TERMS AND CONDITIONS
 
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2025 Simone Avogadro
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -199,4 +187,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.

package/bundled-skills/android-reverse-engineering/references/api-extraction-patterns.md

@@ -0,0 +1,197 @@
+# API Extraction Patterns
+
+Patterns and grep commands for finding HTTP API calls in decompiled Android source code.
+
+## Retrofit
+
+Retrofit is the most common HTTP client in Android apps. API endpoints are declared as annotated interface methods.
+
+### Annotations to search for
+
+```bash
+# HTTP method annotations
+grep -rn '@GET\|@POST\|@PUT\|@DELETE\|@PATCH\|@HEAD' sources/
+
+# Parameter annotations
+grep -rn '@Query\|@QueryMap\|@Path\|@Body\|@Field\|@FieldMap\|@Part\|@Header\|@HeaderMap' sources/
+
+# Headers annotation (static headers)
+grep -rn '@Headers' sources/
+
+# Base URL configuration
+grep -rn 'baseUrl\|\.baseUrl(' sources/
+```
+
+### Typical Retrofit interface
+
+```java
+public interface ApiService {
+    @GET("users/{id}")
+    Call<User> getUser(@Path("id") String userId);
+
+    @POST("auth/login")
+    @Headers({"Content-Type: application/json"})
+    Call<LoginResponse> login(@Body LoginRequest request);
+}
+```
+
+When documenting, capture: HTTP method, path, path parameters, query parameters, request body type, response type, and any static headers.
+
+## OkHttp
+
+OkHttp is often used directly or as the transport layer for Retrofit.
+
+```bash
+# Request building
+grep -rn 'Request\.Builder\|Request.Builder\|\.url(\|\.post(\|\.put(\|\.delete(\|\.patch(' sources/
+
+# URL construction
+grep -rn 'HttpUrl\|\.addQueryParameter\|\.addPathSegment' sources/
+
+# Interceptors (often add auth headers)
+grep -rn 'Interceptor\|addInterceptor\|addNetworkInterceptor\|intercept(' sources/
+
+# Response handling
+grep -rn '\.execute()\|\.enqueue(' sources/
+```
+
+## Ktor (Kotlin)
+
+Ktor is the dominant HTTP client in Kotlin Multiplatform and modern
+Kotlin-only Android apps. Unlike Retrofit, Ktor does **not** use annotations
+to declare endpoints — paths appear as plain string arguments to
+`client.get(...)` / `client.post(...)`, often inside an extension function.
+
+```bash
+# Calls
+grep -rn '\b\(client\|httpClient\|HttpClient\)\.\(get\|post\|put\|delete\|patch\|head\|request\)\s*[<(]' sources/
+
+# Default request / base URL configuration
+grep -rn 'HttpRequestBuilder\|defaultRequest\s*{\|\burl\s*(\s*"\|URLBuilder' sources/
+
+# Auth plugin (bearer / refresh)
+grep -rn '\bbearer\s*{\|BearerTokens\s*(\|loadTokens\s*{\|refreshTokens\s*{' sources/
+```
+
+Typical Ktor call (after decompile):
+
+```java
+client.get("api/v1/users/profile") {
+    parameter("locale", "en-US");
+}
+```
+
+The base URL is usually applied via `defaultRequest { url { host = "..." } }`
+in the client builder. Search for `host =` and `URLProtocol.HTTPS` references
+to pin it down.
+
+**Note on obfuscation:** in heavily R8-shrunk apps the call site
+`client.get("path")` is inlined to something like `aVar.a(dVar, "path")`
+and the `client.<verb>(` regex misses it. The path string itself is **not**
+obfuscated, however — fall back to the generic path-literal search
+(`--paths`) for the endpoint inventory in those cases. Ktor library
+internals (`BearerTokens`, `loadTokens`, `refreshTokens`, `URLProtocol`)
+remain searchable because Ktor keeps these on its public API.
+
+Ktor's authentication plugin uses the
+[`Auth { bearer { loadTokens { ... }; refreshTokens { ... } } }`](https://ktor.io/docs/auth.html)
+DSL — bearer access tokens with automatic refresh. After R8, the DSL
+lambdas appear as `Function2`/`Function3` impls referencing
+`BearerTokens(...)` calls.
+
+## Apollo Kotlin (GraphQL)
+
+```bash
+# Client setup
+grep -rn 'ApolloClient\|\.serverUrl(\|HttpNetworkTransport' sources/
+
+# Operations (queries / mutations / subscriptions)
+grep -rn '\.query(\s*[A-Z]\|\.mutation(\s*[A-Z]\|\.subscription(\s*[A-Z]' sources/
+```
+
+Apollo generates one class per operation under a generated package; once you
+find the GraphQL endpoint URL via `ApolloClient.serverUrl("...")`, use the
+operation classes themselves as the API documentation — each carries its
+GraphQL document text in `OPERATION_DOCUMENT`.
+
+## Volley
+
+```bash
+grep -rn 'StringRequest\|JsonObjectRequest\|JsonArrayRequest\|Volley\.newRequestQueue\|RequestQueue' sources/
+```
+
+Volley requests typically pass the URL as a constructor argument and override `getHeaders()` or `getParams()` for custom headers/parameters.
+
+## HttpURLConnection (legacy)
+
+```bash
+grep -rn 'HttpURLConnection\|HttpsURLConnection\|openConnection\|setRequestMethod\|setRequestProperty' sources/
+```
+
+## WebView
+
+```bash
+grep -rn 'loadUrl\|evaluateJavascript\|addJavascriptInterface\|WebViewClient\|shouldOverrideUrlLoading' sources/
+```
+
+WebView-based apps may load API endpoints via JavaScript bridges. Look for `@JavascriptInterface` annotated methods.
+
+## Endpoint-Shaped Path Literals (obfuscation-resistant)
+
+When the HTTP client cannot be identified (custom abstraction, heavy
+inlining, KMP shared module), or the call sites are obfuscated to
+`a.b(c, "path")`, fall back to extracting the path string literals
+themselves. R8 does not obfuscate string contents, so paths leak through.
+
+```bash
+# All quoted strings shaped like an API path, deduplicated
+grep -rhoE '"(/[A-Za-z0-9_{}.\-]+(/[A-Za-z0-9_{}.\-]+)+/?|(api|v[0-9]+|graphql|users?|account|auth|sso|oauth|profile|cart|basket|order|product|inventory|search|category|address|location|delivery|payment|invoice|favo[u]?rites?)(/[A-Za-z0-9_{}.\-]+)+/?)"' sources/ \
+    | grep -Ev '^"(image|video|audio|text|application|content)/|^"/(proc|sys|dev|tmp|etc)/' \
+    | sort -u
+```
+
+The skill ships this as `find-api-calls.sh --paths`, which prints both a
+deduplicated inventory and the full list of call sites. On real-world
+Kotlin apps this single command typically produces 100–300 distinct
+endpoint paths, which is the most useful first artifact for documentation.
+
+## Hardcoded URLs and Secrets
+
+```bash
+# HTTP/HTTPS URLs
+grep -rn '"https\?://[^"]*"' sources/
+
+# API keys and tokens
+grep -rni 'api[_-]\?key\|api[_-]\?secret\|auth[_-]\?token\|bearer\|access[_-]\?token\|client[_-]\?secret' sources/
+
+# Base URL constants
+grep -rni 'BASE_URL\|API_URL\|SERVER_URL\|ENDPOINT\|API_BASE' sources/
+```
+
+## Documentation Template
+
+For each discovered API endpoint, document it using this template:
+
+```markdown
+### `METHOD /path/to/endpoint`
+
+- **Source**: `com.example.app.api.ApiService` (file:line)
+- **Base URL**: `https://api.example.com/v1`
+- **Full URL**: `https://api.example.com/v1/path/to/endpoint`
+- **Path parameters**: `id` (String)
+- **Query parameters**: `page` (int), `limit` (int)
+- **Headers**:
+  - `Authorization: Bearer <token>`
+  - `Content-Type: application/json`
+- **Request body**: `LoginRequest { email: String, password: String }`
+- **Response type**: `ApiResponse<User>`
+- **Notes**: Called from `LoginActivity.onLoginClicked()`
+```
+
+## Search Strategy
+
+1. Start with **base URL constants** — find where the API root is configured
+2. Search for **Retrofit interfaces** — they give the clearest picture of all endpoints
+3. Check **interceptors** — they reveal auth schemes and common headers
+4. Search for **hardcoded URLs** — catch any one-off API calls outside the main client
+5. Look for **WebView URLs** — some apps use hybrid web/native approaches