@polterware/polterbase 0.2.5 → 0.2.6

package/README.md

@@ -21,6 +21,7 @@ Polterbase is a productivity layer on top of the official `supabase` CLI. Instea
 - **Built-in Self-Update**: Update Polterbase for the current repository or globally through npm
 - **Shell Execution**: Resolves `supabase` from the current repository first, then falls back to `PATH`
 - **TypeScript-based CLI**: Strongly typed internal implementation
+- **App Workflows**: Explicit `polterbase app ...` flows for repository-aware setup, linking, migrations, runtime configuration, and app installation
 
 ---
 
@@ -102,6 +103,39 @@ Install Supabase CLI (official docs):
 
 ## Quick Reference
 
+### App Workflows
+
+Polterbase keeps generic Supabase execution separate from app-specific automation.
+Use the `app` namespace when you want project-aware workflows:
+
+```bash
+polterbase app setup uru --path .
+```
+
+```bash
+polterbase app link uru --path .
+```
+
+```bash
+polterbase app migrate uru push --path .
+```
+
+```bash
+polterbase app configure uru --path .
+```
+
+```bash
+polterbase app install uru --platform macos
+```
+
+`setup uru` installs dependencies, collects Supabase connection data, links the project, pushes migrations, and writes the runtime bootstrap payload used by the desktop app.
+
+`configure uru` refreshes the runtime connection payload without reinstalling the app.
+
+`install uru` is currently macOS-only. By default it resolves the latest GitHub release from `polterware/uru`, accepts `--version <version>` to pin a release, and still supports `--artifact-url` or `POLTERBASE_URU_MACOS_ARTIFACT_URL` as manual overrides.
+
+Use `POLTERBASE_URU_GITHUB_REPO=owner/repo` when you need to resolve releases from a fork or a different repository.
+
 ### Execution Model
 
 Polterbase executes workflow commands as:
@@ -220,6 +254,30 @@ Pins are persisted locally using OS-level app config storage.
 
 ## Usage Examples
 
+### Bootstrap Uru from source
+
+```bash
+polterbase app setup uru --path /absolute/path/to/uru
+```
+
+### Reconfigure an installed Uru app
+
+```bash
+polterbase app configure uru
+```
+
+### Install the latest released Uru app
+
+```bash
+polterbase app install uru --platform macos
+```
+
+Install a specific release:
+
+```bash
+polterbase app install uru --platform macos --version 1.0.0
+```
+
 ### Check Supabase CLI version
 
 Interactive path:

package/dist/index.js

@@ -43,7 +43,7 @@ var SUPABASE_FG = "\x1B[38;2;62;207;142m";
 var SUPABASE_BG = "\x1B[48;2;62;207;142m";
 var RESET_FG = "\x1B[39m";
 var RESET_BG = "\x1B[49m";
-var wrapAnsi = (open, close) => (input) => pc.isColorSupported ? `${open}${input}${close}` : input;
+var wrapAnsi = (open, close) => (input2) => pc.isColorSupported ? `${open}${input2}${close}` : input2;
 var supabase = wrapAnsi(SUPABASE_FG, RESET_FG);
 var supabaseBg = wrapAnsi(SUPABASE_BG, RESET_BG);
 var VERSION = packageJson.version;
@@ -229,21 +229,21 @@ function SelectList({
   }, [selectableIndexes]);
   const selectedItemIndex = selectableIndexes[selectedSelectableIndex] ?? -1;
   const selectedItem = selectedItemIndex >= 0 ? items[selectedItemIndex] : void 0;
-  useInput((input, key) => {
+  useInput((input2, key) => {
     if (selectableIndexes.length === 0) {
       if (key.escape && onCancel) {
         onCancel();
       }
       return;
     }
-    if (key.upArrow || input === "k") {
+    if (key.upArrow || input2 === "k") {
       setSelectedSelectableIndex((prev) => {
         let next = prev - 1;
         if (next < 0) next = selectableIndexes.length - 1;
         return next;
       });
     }
-    if (key.downArrow || input === "j") {
+    if (key.downArrow || input2 === "j") {
       setSelectedSelectableIndex((prev) => {
         let next = prev + 1;
         if (next >= selectableIndexes.length) next = 0;
@@ -1201,14 +1201,14 @@ function FlagToggle({
 }) {
   const [cursor, setCursor] = useState6(0);
   const [selected, setSelected] = useState6(/* @__PURE__ */ new Set());
-  useInput3((input, key) => {
-    if (key.upArrow || input === "k") {
+  useInput3((input2, key) => {
+    if (key.upArrow || input2 === "k") {
       setCursor((prev) => prev > 0 ? prev - 1 : flags.length - 1);
     }
-    if (key.downArrow || input === "j") {
+    if (key.downArrow || input2 === "j") {
       setCursor((prev) => prev < flags.length - 1 ? prev + 1 : 0);
     }
-    if (input === " ") {
+    if (input2 === " ") {
       setSelected((prev) => {
         const next = new Set(prev);
         const flag = flags[cursor];
@@ -1326,12 +1326,12 @@ function ConfirmPrompt({
   defaultValue = true,
   onConfirm
 }) {
-  useInput4((input) => {
-    if (input === "y" || input === "Y") {
+  useInput4((input2) => {
+    if (input2 === "y" || input2 === "Y") {
       onConfirm(true);
-    } else if (input === "n" || input === "N") {
+    } else if (input2 === "n" || input2 === "N") {
       onConfirm(false);
-    } else if (input === "\r") {
+    } else if (input2 === "\r") {
       onConfirm(defaultValue);
     }
   });
@@ -1422,7 +1422,7 @@ function resolveSupabaseCommand(startDir = process.cwd(), env = process.env) {
   };
 }
 async function runCommand(execution, args, cwd = process.cwd()) {
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     let stdout = "";
     let stderr = "";
     const resolvedExecution = typeof execution === "string" ? { command: execution } : execution;
@@ -1443,7 +1443,7 @@ async function runCommand(execution, args, cwd = process.cwd()) {
       process.stderr.write(text);
     });
     child.on("error", (err) => {
-      resolve3({
+      resolve4({
         exitCode: null,
         signal: null,
         stdout,
@@ -1452,7 +1452,7 @@ async function runCommand(execution, args, cwd = process.cwd()) {
       });
     });
     child.on("exit", (code, signal) => {
-      resolve3({ exitCode: code, signal, stdout, stderr });
+      resolve4({ exitCode: code, signal, stdout, stderr });
     });
   });
 }
@@ -1486,19 +1486,19 @@ function useCommand(execution = "supabase", cwd = process.cwd()) {
 // src/lib/clipboard.ts
 import { spawn as spawn2, exec } from "child_process";
 async function openInBrowser(url) {
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     const cmd = process.platform === "darwin" ? `open "${url}"` : process.platform === "win32" ? `start "${url}"` : `xdg-open "${url}"`;
-    exec(cmd, () => resolve3());
+    exec(cmd, () => resolve4());
   });
 }
 async function copyToClipboard(text) {
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     const cmd = process.platform === "darwin" ? "pbcopy" : process.platform === "win32" ? "clip" : "xclip -selection clipboard";
     const child = spawn2(cmd, [], { shell: true });
     child.stdin?.write(text);
     child.stdin?.end();
-    child.on("exit", () => resolve3());
-    child.on("error", () => resolve3());
+    child.on("exit", () => resolve4());
+    child.on("error", () => resolve4());
   });
 }
 
@@ -1993,5 +1993,920 @@ function App() {
   }
 }
 
+// src/lib/cliArgs.ts
+function takeValue(args, index) {
+  const token = args[index];
+  if (!token) {
+    return { nextIndex: index };
+  }
+  const eqIndex = token.indexOf("=");
+  if (eqIndex >= 0) {
+    return {
+      value: token.slice(eqIndex + 1),
+      nextIndex: index
+    };
+  }
+  return { value: args[index + 1], nextIndex: index + 1 };
+}
+function parseCliArgs(argv) {
+  if (argv.length === 0) {
+    return { mode: "interactive", options: {} };
+  }
+  if (argv[0] === "--help" || argv[0] === "help") {
+    return { mode: "help", options: {} };
+  }
+  if (argv[0] !== "app") {
+    return { mode: "interactive", options: {} };
+  }
+  const options = {};
+  options.action = argv[1];
+  options.app = argv[2];
+  for (let index = 3; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "push" || token === "lint" || token === "reset" || token === "local-reset") {
+      options.migrationAction = token;
+      continue;
+    }
+    if (token === "--yes") {
+      options.yes = true;
+      continue;
+    }
+    if (token === "--relink") {
+      options.relink = true;
+      continue;
+    }
+    if (token === "--create-project") {
+      options.createProject = true;
+      continue;
+    }
+    if (token === "--use-existing-project") {
+      options.useExistingProject = true;
+      continue;
+    }
+    if (token.startsWith("--path")) {
+      const parsed = takeValue(argv, index);
+      options.path = parsed.value;
+      index = parsed.nextIndex;
+      continue;
+    }
+    if (token.startsWith("--platform")) {
+      const parsed = takeValue(argv, index);
+      options.platform = parsed.value;
+      index = parsed.nextIndex;
+      continue;
+    }
+    if (token.startsWith("--version")) {
+      const parsed = takeValue(argv, index);
+      options.version = parsed.value;
+      index = parsed.nextIndex;
+      continue;
+    }
+    if (token.startsWith("--artifact-url")) {
+      const parsed = takeValue(argv, index);
+      options.artifactUrl = parsed.value;
+      index = parsed.nextIndex;
+      continue;
+    }
+    if (token.startsWith("--install-dir")) {
+      const parsed = takeValue(argv, index);
+      options.installDir = parsed.value;
+      index = parsed.nextIndex;
+      continue;
+    }
+  }
+  return {
+    mode: "app",
+    options
+  };
+}
+function printCliHelp() {
+  process.stdout.write(
+    [
+      "Polterbase",
+      "",
+      "Usage:",
+      "  polterbase",
+      "  polterbase app setup uru [--path <dir>] [--create-project|--use-existing-project] [--yes]",
+      "  polterbase app link uru [--path <dir>] [--relink]",
+      "  polterbase app migrate uru [push|lint|reset|local-reset] [--path <dir>] [--relink]",
+      "  polterbase app configure uru [--path <dir>] [--yes]",
+      "  polterbase app install uru --platform macos [--version <version>] [--artifact-url <url>] [--install-dir <dir>] [--yes]",
+      "",
+      "Notes:",
+      "  - App workflows stay separate from the generic Supabase interactive menu.",
+      "  - `install uru` resolves the latest GitHub release from polterware/uru by default.",
+      "  - Use --artifact-url or POLTERBASE_URU_MACOS_ARTIFACT_URL to override the downloaded asset.",
+      "  - Use POLTERBASE_URU_GITHUB_REPO=owner/repo to resolve releases from a different repository.",
+      ""
+    ].join("\n")
+  );
+}
+
+// src/apps/runAppCli.ts
+import pc3 from "picocolors";
+
+// src/apps/uru.ts
+import { existsSync as existsSync3, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { mkdtemp, readdir, stat } from "fs/promises";
+import { dirname as dirname3, join as join4, resolve as resolve3 } from "path";
+import { tmpdir } from "os";
+import pc2 from "picocolors";
+
+// src/apps/bootstrapPaths.ts
+import { homedir } from "os";
+import { join as join3 } from "path";
+function getUruBootstrapPayloadPath() {
+  const home = homedir();
+  if (process.platform === "darwin") {
+    return join3(
+      home,
+      "Library",
+      "Application Support",
+      "uru",
+      "bootstrap",
+      "supabase.json"
+    );
+  }
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA ?? join3(home, "AppData", "Roaming");
+    return join3(appData, "uru", "bootstrap", "supabase.json");
+  }
+  return join3(home, ".config", "uru", "bootstrap", "supabase.json");
+}
+
+// src/apps/uruRelease.ts
+var DEFAULT_URU_GITHUB_REPO = "polterware/uru";
+var DEFAULT_ARTIFACT_ENV_VAR = "POLTERBASE_URU_MACOS_ARTIFACT_URL";
+var DEFAULT_GITHUB_REPO_ENV_VAR = "POLTERBASE_URU_GITHUB_REPO";
+var GITHUB_API_BASE = "https://api.github.com/repos";
+function getGitHubHeaders(env) {
+  const headers = {
+    Accept: "application/vnd.github+json",
+    "X-GitHub-Api-Version": "2022-11-28"
+  };
+  const token = env.GITHUB_TOKEN?.trim() || env.GH_TOKEN?.trim();
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+  return headers;
+}
+function getGitHubReleaseRequestLabel(repo, version) {
+  if (!version) {
+    return `latest release in ${repo}`;
+  }
+  return `release ${version} in ${repo}`;
+}
+function parseGitHubReleaseAsset(value) {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const asset = value;
+  const name = typeof asset.name === "string" ? asset.name.trim() : "";
+  const browserDownloadUrl = typeof asset.browser_download_url === "string" ? asset.browser_download_url.trim() : "";
+  const size = typeof asset.size === "number" ? asset.size : void 0;
+  if (!name || !browserDownloadUrl) {
+    return null;
+  }
+  return {
+    name,
+    browserDownloadUrl,
+    size
+  };
+}
+async function parseGitHubReleaseResponse(response, label) {
+  const body = await response.text();
+  if (!response.ok) {
+    let detail = body.trim();
+    try {
+      const parsed2 = JSON.parse(body);
+      if (typeof parsed2.message === "string" && parsed2.message.trim()) {
+        detail = parsed2.message.trim();
+      }
+    } catch {
+    }
+    throw new Error(
+      `Unable to resolve ${label}: ${response.status} ${response.statusText}${detail ? ` (${detail})` : ""}.`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch (error) {
+    throw new Error(
+      `Unable to parse ${label} from GitHub: ${error instanceof Error ? error.message : String(error)}.`
+    );
+  }
+  const assets = Array.isArray(parsed.assets) ? parsed.assets.map((asset) => parseGitHubReleaseAsset(asset)).filter((asset) => asset !== null) : [];
+  if (assets.length === 0) {
+    throw new Error(`GitHub ${label} did not contain any downloadable assets.`);
+  }
+  return {
+    tagName: typeof parsed.tag_name === "string" ? parsed.tag_name : null,
+    assets
+  };
+}
+function normalizeUruReleaseVersion(version) {
+  return version.trim().replace(/^v/i, "");
+}
+function buildVersionTagCandidates(version) {
+  const normalized = normalizeUruReleaseVersion(version);
+  if (!normalized) {
+    return [];
+  }
+  return Array.from(/* @__PURE__ */ new Set([`v${normalized}`, normalized]));
+}
+async function fetchGitHubRelease(repo, version, fetchImpl, env) {
+  const headers = getGitHubHeaders(env);
+  if (version) {
+    const tagCandidates = buildVersionTagCandidates(version);
+    for (const tag of tagCandidates) {
+      const response2 = await fetchImpl(
+        `${GITHUB_API_BASE}/${repo}/releases/tags/${encodeURIComponent(tag)}`,
+        { headers }
+      );
+      if (response2.status === 404) {
+        continue;
+      }
+      return parseGitHubReleaseResponse(
+        response2,
+        getGitHubReleaseRequestLabel(repo, tag)
+      );
+    }
+    throw new Error(
+      `Unable to find release ${normalizeUruReleaseVersion(version)} in ${repo}.`
+    );
+  }
+  const response = await fetchImpl(`${GITHUB_API_BASE}/${repo}/releases/latest`, {
+    headers
+  });
+  return parseGitHubReleaseResponse(
+    response,
+    getGitHubReleaseRequestLabel(repo)
+  );
+}
+function getArtifactFileNameFromUrl(url, fallback = "uru-macos.zip") {
+  try {
+    const pathname = new URL(url).pathname;
+    const name = decodeURIComponent(pathname.split("/").pop() ?? "").trim();
+    return name || fallback;
+  } catch {
+    const name = decodeURIComponent(url.split("?")[0]?.split("/").pop() ?? "").trim();
+    return name || fallback;
+  }
+}
+function hasSupportedArchiveFormat(name) {
+  const lowered = name.toLowerCase();
+  return lowered.endsWith(".app.tar.gz") || lowered.endsWith(".zip");
+}
+function hasMacosHint(name) {
+  const lowered = name.toLowerCase();
+  return lowered.endsWith(".app.tar.gz") || lowered.includes(".app.zip") || lowered.includes("macos") || lowered.includes("darwin") || lowered.includes("universal");
+}
+function isSupportedUruMacosArtifactName(name) {
+  return hasSupportedArchiveFormat(name) && hasMacosHint(name);
+}
+function getArchAliases(arch) {
+  switch (arch) {
+    case "arm64":
+    case "aarch64":
+      return ["arm64", "aarch64"];
+    case "x64":
+    case "x86_64":
+    case "amd64":
+      return ["x64", "x86_64", "amd64"];
+    default:
+      return [arch.toLowerCase()];
+  }
+}
+function hasAnyArchHint(name) {
+  return /(arm64|aarch64|x64|x86_64|amd64)/.test(name.toLowerCase());
+}
+function getArchPriority(name, arch) {
+  const lowered = name.toLowerCase();
+  if (lowered.includes("universal")) {
+    return 0;
+  }
+  const aliases = getArchAliases(arch);
+  if (aliases.some((alias) => lowered.includes(alias))) {
+    return 1;
+  }
+  if (hasAnyArchHint(lowered)) {
+    return 3;
+  }
+  return 2;
+}
+function getFormatPriority(name) {
+  return name.toLowerCase().endsWith(".app.tar.gz") ? 0 : 1;
+}
+function selectUruMacosReleaseAsset(assets, arch = process.arch) {
+  const supported = assets.map((asset, index) => ({ asset, index })).filter(({ asset }) => isSupportedUruMacosArtifactName(asset.name)).sort((left, right) => {
+    const archPriority = getArchPriority(left.asset.name, arch) - getArchPriority(right.asset.name, arch);
+    if (archPriority !== 0) {
+      return archPriority;
+    }
+    const formatPriority = getFormatPriority(left.asset.name) - getFormatPriority(right.asset.name);
+    if (formatPriority !== 0) {
+      return formatPriority;
+    }
+    return left.index - right.index;
+  });
+  if (supported.length === 0) {
+    const names = assets.map((asset) => asset.name).join(", ");
+    throw new Error(
+      `No supported macOS archive was found in the release. Expected a .app.tar.gz or .zip asset for macOS, found: ${names}.`
+    );
+  }
+  return supported[0].asset;
+}
+async function resolveUruMacosArtifact(options, env = process.env, fetchImpl = fetch, arch = process.arch) {
+  const explicitUrl = options.artifactUrl?.trim() || env[DEFAULT_ARTIFACT_ENV_VAR]?.trim();
+  if (explicitUrl) {
+    return {
+      url: explicitUrl,
+      fileName: getArtifactFileNameFromUrl(explicitUrl),
+      source: "explicit-url"
+    };
+  }
+  const repo = env[DEFAULT_GITHUB_REPO_ENV_VAR]?.trim() || DEFAULT_URU_GITHUB_REPO;
+  const release = await fetchGitHubRelease(repo, options.version, fetchImpl, env);
+  const asset = selectUruMacosReleaseAsset(release.assets, arch);
+  return {
+    url: asset.browserDownloadUrl,
+    fileName: asset.name,
+    size: asset.size,
+    source: "github-release",
+    repo,
+    tagName: release.tagName
+  };
+}
+
+// src/lib/prompts.ts
+import { createInterface } from "readline/promises";
+import { stdin as input, stdout as output } from "process";
+async function promptText(label, options = {}) {
+  const rl = createInterface({ input, output });
+  try {
+    while (true) {
+      const suffix = options.defaultValue ? ` (${options.defaultValue})` : "";
+      const answer = (await rl.question(`${label}${suffix}: `)).trim();
+      if (!answer && options.defaultValue) {
+        return options.defaultValue;
+      }
+      if (!answer && options.required) {
+        output.write("This value is required.\n");
+        continue;
+      }
+      return answer;
+    }
+  } finally {
+    rl.close();
+  }
+}
+async function promptConfirm(label, defaultValue = true) {
+  const rl = createInterface({ input, output });
+  try {
+    const answer = (await rl.question(`${label} ${defaultValue ? "(Y/n)" : "(y/N)"}: `)).trim().toLowerCase();
+    if (!answer) {
+      return defaultValue;
+    }
+    return answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+async function promptSelect(label, options, defaultValue) {
+  const rl = createInterface({ input, output });
+  try {
+    output.write(`${label}
+`);
+    for (const [index, option] of options.entries()) {
+      const marker = option.value === defaultValue ? " (default)" : "";
+      output.write(`  ${index + 1}. ${option.label}${marker}
+`);
+    }
+    while (true) {
+      const answer = (await rl.question(
+        `Choose 1-${options.length}${defaultValue ? " (press Enter for default)" : ""}: `
+      )).trim();
+      if (!answer && defaultValue) {
+        return defaultValue;
+      }
+      const selectedIndex = Number(answer);
+      if (Number.isInteger(selectedIndex) && selectedIndex >= 1 && selectedIndex <= options.length) {
+        return options[selectedIndex - 1].value;
+      }
+      output.write("Invalid selection.\n");
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+// src/lib/system.ts
+import { execSync } from "child_process";
+function commandExists(command) {
+  try {
+    execSync(`command -v ${command}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/apps/uru.ts
+var LINK_REF_FILE = join4("supabase", ".temp", "project-ref");
+function isUruProjectRoot(candidate) {
+  return existsSync3(join4(candidate, "src-tauri", "tauri.conf.json")) && existsSync3(join4(candidate, "supabase", "migrations")) && existsSync3(join4(candidate, "package.json"));
+}
+function findNearestUruRoot(startDir) {
+  let currentDir = resolve3(startDir);
+  while (true) {
+    if (isUruProjectRoot(currentDir)) {
+      return currentDir;
+    }
+    const siblingCandidate = join4(currentDir, "uru");
+    if (isUruProjectRoot(siblingCandidate)) {
+      return siblingCandidate;
+    }
+    const parentDir = dirname3(currentDir);
+    if (parentDir === currentDir) {
+      return void 0;
+    }
+    currentDir = parentDir;
+  }
+}
+function readEnvFile(envPath) {
+  if (!existsSync3(envPath)) {
+    return {};
+  }
+  const content = readFileSync(envPath, "utf-8");
+  const entries = {};
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+    const eqIndex = trimmed.indexOf("=");
+    if (eqIndex === -1) {
+      continue;
+    }
+    const key = trimmed.slice(0, eqIndex).trim();
+    const value = trimmed.slice(eqIndex + 1).trim();
+    entries[key] = value;
+  }
+  return entries;
+}
+function writeEnvFile(envPath, nextEnv) {
+  const content = Object.entries(nextEnv).map(([key, value]) => `${key}=${value}`).join("\n");
+  writeFileSync(envPath, `${content}
+`);
+}
+function assertProjectRoot(projectRoot) {
+  if (!projectRoot) {
+    throw new Error(
+      "Could not resolve the Uru project root. Run from the Uru repository or pass --path."
+    );
+  }
+  return projectRoot;
+}
+function getLinkedProjectRef(projectRoot) {
+  const refPath = join4(projectRoot, LINK_REF_FILE);
+  if (!existsSync3(refPath)) {
+    return null;
+  }
+  const value = readFileSync(refPath, "utf-8").trim();
+  return value || null;
+}
+function getDbPasswordArgs() {
+  const password = process.env.SUPABASE_DB_PASSWORD?.trim();
+  return password ? ["--password", password] : [];
+}
+async function ensurePrerequisites() {
+  const checks = [
+    { command: "node", label: "Node.js" },
+    { command: "pnpm", label: "pnpm" },
+    { command: "supabase", label: "Supabase CLI" }
+  ];
+  const missing = checks.filter((check) => !commandExists(check.command));
+  if (missing.length > 0) {
+    throw new Error(
+      `Missing required tools: ${missing.map((item) => item.label).join(", ")}`
+    );
+  }
+}
+async function runOrThrow(execution, args, cwd, failureMessage) {
+  const result = await runCommand(execution, args, cwd);
+  if (result.spawnError || result.exitCode !== 0) {
+    throw new Error(
+      result.stderr.trim() || result.spawnError || failureMessage
+    );
+  }
+}
+async function runSupabaseOrThrow(args, cwd, failureMessage) {
+  const result = await runSupabaseCommand(args, cwd);
+  if (result.spawnError || result.exitCode !== 0) {
+    throw new Error(
+      result.stderr.trim() || result.spawnError || failureMessage
+    );
+  }
+}
+async function ensureSupabaseLink(projectRoot, forceRelink = false) {
+  const linkedRef = getLinkedProjectRef(projectRoot);
+  if (linkedRef && !forceRelink) {
+    process.stdout.write(`${pc2.dim(`Linked project: ${linkedRef}`)}
+`);
+    return;
+  }
+  process.stdout.write(
+    `${pc2.dim(forceRelink ? "Relinking Supabase project..." : "Linking Supabase project...")}
+`
+  );
+  await runSupabaseOrThrow(
+    ["link", ...getDbPasswordArgs()],
+    projectRoot,
+    "Supabase link failed."
+  );
+}
+async function collectSupabaseConfig(projectRoot) {
+  const envPath = projectRoot ? join4(projectRoot, ".env.local") : void 0;
+  const currentEnv = envPath ? readEnvFile(envPath) : {};
+  const currentRef = projectRoot ? getLinkedProjectRef(projectRoot) : null;
+  const url = await promptText("Supabase URL", {
+    defaultValue: currentEnv.VITE_SUPABASE_URL,
+    required: true
+  });
+  const publishableKey = await promptText("Supabase publishable key", {
+    defaultValue: currentEnv.VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY,
+    required: true
+  });
+  const projectRef = await promptText("Supabase project ref", {
+    defaultValue: currentRef ?? "",
+    required: true
+  });
+  return {
+    url: url.trim().replace(/\/$/, ""),
+    publishableKey: publishableKey.trim(),
+    projectRef: projectRef.trim()
+  };
+}
+function writeUruEnv(projectRoot, config2) {
+  const envPath = join4(projectRoot, ".env.local");
+  const currentEnv = readEnvFile(envPath);
+  const nextEnv = {
+    ...currentEnv,
+    VITE_SUPABASE_URL: config2.url,
+    VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY: config2.publishableKey
+  };
+  writeEnvFile(envPath, nextEnv);
+}
+function writeBootstrapPayload(config2) {
+  const payloadPath = getUruBootstrapPayloadPath();
+  mkdirSync(dirname3(payloadPath), { recursive: true });
+  writeFileSync(
+    payloadPath,
+    JSON.stringify(
+      {
+        url: config2.url,
+        publishableKey: config2.publishableKey,
+        projectRef: config2.projectRef,
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        source: "polterbase"
+      },
+      null,
+      2
+    )
+  );
+  return payloadPath;
+}
+async function promptProjectMode(options) {
+  if (options.useExistingProject) {
+    return "existing";
+  }
+  if (options.createProject) {
+    return "create";
+  }
+  const selected = await promptSelect(
+    "How should Polterbase prepare Supabase for Uru?",
+    [
+      { value: "existing", label: "Use an existing Supabase project" },
+      { value: "create", label: "Create a new Supabase project first" }
+    ],
+    "existing"
+  );
+  return selected;
+}
+async function runSetup(context) {
+  const projectRoot = assertProjectRoot(context.projectRoot);
+  await ensurePrerequisites();
+  const mode = await promptProjectMode(context.options);
+  if (mode === "create") {
+    process.stdout.write(
+      `${pc2.dim("Launching interactive Supabase project creation...")}
+`
+    );
+    await runSupabaseOrThrow(
+      ["projects", "create"],
+      projectRoot,
+      "Supabase project creation failed."
+    );
+  }
+  const config2 = await collectSupabaseConfig(projectRoot);
+  writeUruEnv(projectRoot, config2);
+  process.stdout.write(`${pc2.green("Saved .env.local")}
+`);
+  process.stdout.write(`${pc2.dim("Installing project dependencies...")}
+`);
+  await runOrThrow(
+    "pnpm",
+    ["install", "--frozen-lockfile"],
+    projectRoot,
+    "Dependency installation failed."
+  );
+  await ensureSupabaseLink(projectRoot, context.options.relink);
+  process.stdout.write(`${pc2.dim("Pushing migrations to linked project...")}
+`);
+  await runSupabaseOrThrow(
+    ["db", "push", "--linked", ...getDbPasswordArgs()],
+    projectRoot,
+    "Migration push failed."
+  );
+  const payloadPath = writeBootstrapPayload(config2);
+  process.stdout.write(`${pc2.green("Prepared runtime bootstrap payload")}
+`);
+  process.stdout.write(`${pc2.dim(`Payload path: ${payloadPath}`)}
+`);
+  return 0;
+}
+async function runLink(context) {
+  const projectRoot = assertProjectRoot(context.projectRoot);
+  await ensurePrerequisites();
+  await ensureSupabaseLink(projectRoot, true);
+  process.stdout.write(`${pc2.green("Supabase link completed")}
+`);
+  return 0;
+}
+async function runMigration(context, action) {
+  const projectRoot = assertProjectRoot(context.projectRoot);
+  await ensurePrerequisites();
+  switch (action) {
+    case "local-reset":
+      await runSupabaseOrThrow(
+        ["db", "reset", "--local"],
+        projectRoot,
+        "Local reset failed."
+      );
+      process.stdout.write(`${pc2.green("Local Supabase reset completed")}
+`);
+      return 0;
+    case "push":
+      await ensureSupabaseLink(projectRoot, context.options.relink);
+      await runSupabaseOrThrow(
+        ["db", "push", "--linked", ...getDbPasswordArgs()],
+        projectRoot,
+        "Migration push failed."
+      );
+      process.stdout.write(`${pc2.green("Migrations pushed")}
+`);
+      return 0;
+    case "lint":
+      await ensureSupabaseLink(projectRoot, context.options.relink);
+      await runSupabaseOrThrow(
+        ["db", "lint", "--linked"],
+        projectRoot,
+        "Migration lint failed."
+      );
+      process.stdout.write(`${pc2.green("Migration lint completed")}
+`);
+      return 0;
+    case "reset":
+      await ensureSupabaseLink(projectRoot, context.options.relink);
+      if (!context.options.yes) {
+        const confirmed = await promptConfirm(
+          "This will reset the linked remote database. Continue?",
+          false
+        );
+        if (!confirmed) {
+          process.stdout.write(`${pc2.yellow("Cancelled.")}
+`);
+          return 0;
+        }
+      }
+      await runSupabaseOrThrow(
+        ["db", "reset", "--linked", ...getDbPasswordArgs()],
+        projectRoot,
+        "Remote reset failed."
+      );
+      process.stdout.write(`${pc2.green("Remote reset completed")}
+`);
+      return 0;
+  }
+}
+async function runConfigure(context) {
+  const projectRoot = context.projectRoot;
+  const config2 = await collectSupabaseConfig(projectRoot);
+  if (projectRoot) {
+    writeUruEnv(projectRoot, config2);
+    process.stdout.write(`${pc2.green("Updated .env.local")}
+`);
+  }
+  const payloadPath = writeBootstrapPayload(config2);
+  process.stdout.write(`${pc2.green("Updated runtime bootstrap payload")}
+`);
+  process.stdout.write(`${pc2.dim(`Payload path: ${payloadPath}`)}
+`);
+  return 0;
+}
+async function downloadFile(url, destinationPath) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Unable to download artifact: ${response.status} ${response.statusText}`);
+  }
+  const arrayBuffer = await response.arrayBuffer();
+  const buffer = Buffer.from(arrayBuffer);
+  writeFileSync(destinationPath, buffer);
+  return buffer.byteLength;
+}
+async function extractArchive(archivePath, outputDir) {
+  if (archivePath.endsWith(".zip")) {
+    await runOrThrow(
+      "ditto",
+      ["-xk", archivePath, outputDir],
+      process.cwd(),
+      "Archive extraction failed."
+    );
+    return;
+  }
+  if (archivePath.endsWith(".tar.gz") || archivePath.endsWith(".tgz")) {
+    await runOrThrow(
+      "tar",
+      ["-xzf", archivePath, "-C", outputDir],
+      process.cwd(),
+      "Archive extraction failed."
+    );
+    return;
+  }
+  throw new Error("Unsupported artifact format. Use a .zip or .tar.gz macOS artifact.");
+}
+async function findFirstAppBundle(dir) {
+  const entries = await readdir(dir);
+  for (const entry of entries) {
+    const fullPath = join4(dir, entry);
+    const entryStat = await stat(fullPath);
+    if (entryStat.isDirectory() && entry.endsWith(".app")) {
+      return fullPath;
+    }
+    if (entryStat.isDirectory()) {
+      const nested = await findFirstAppBundle(fullPath);
+      if (nested) {
+        return nested;
+      }
+    }
+  }
+  return void 0;
+}
+async function installMacosApp(context) {
+  const artifact = await resolveUruMacosArtifact(context.options);
+  const tempRoot = await mkdtemp(join4(tmpdir(), "polterbase-uru-"));
+  const archivePath = join4(tempRoot, artifact.fileName);
+  const extractDir = join4(tempRoot, "extract");
+  mkdirSync(extractDir, { recursive: true });
+  if (artifact.source === "github-release") {
+    const releaseLabel = artifact.tagName ?? "latest";
+    process.stdout.write(
+      `${pc2.dim(`Resolved ${artifact.fileName} from ${artifact.repo} (${releaseLabel})`)}
+`
+    );
+  } else {
+    process.stdout.write(`${pc2.dim(`Using explicit artifact URL: ${artifact.url}`)}
+`);
+  }
+  process.stdout.write(`${pc2.dim("Downloading Uru macOS artifact...")}
+`);
+  const downloadedSize = await downloadFile(artifact.url, archivePath);
+  if (artifact.size && downloadedSize !== artifact.size) {
+    throw new Error(
+      `Downloaded file size mismatch for ${artifact.fileName}. Expected ${artifact.size} bytes but received ${downloadedSize}.`
+    );
+  }
+  process.stdout.write(`${pc2.dim("Extracting artifact...")}
+`);
+  await extractArchive(archivePath, extractDir);
+  const appBundle = await findFirstAppBundle(extractDir);
+  if (!appBundle) {
+    throw new Error("No .app bundle was found inside the downloaded artifact.");
+  }
+  const installDir = context.options.installDir ?? "/Applications";
+  mkdirSync(installDir, { recursive: true });
+  const destination = join4(installDir, "uru.app");
+  if (existsSync3(destination)) {
+    const confirmed = context.options.yes || await promptConfirm(`Replace existing installation at ${destination}?`, false);
+    if (!confirmed) {
+      process.stdout.write(`${pc2.yellow("Cancelled.")}
+`);
+      return 0;
+    }
+    rmSync(destination, { recursive: true, force: true });
+  }
+  await runOrThrow(
+    "cp",
+    ["-R", appBundle, destination],
+    process.cwd(),
+    "App copy failed."
+  );
+  process.stdout.write(`${pc2.green(`Installed Uru to ${destination}`)}
+`);
+  await runConfigure(context);
+  const shouldOpen = context.options.yes || await promptConfirm("Open Uru now?", true);
+  if (shouldOpen) {
+    await runOrThrow("open", ["-a", destination], process.cwd(), "Unable to open Uru.");
+  }
+  return 0;
+}
+var uruProfile = {
+  id: "uru",
+  displayName: "Uru",
+  detect(startDir = process.cwd()) {
+    return findNearestUruRoot(startDir);
+  },
+  resolveProjectRoot(startDir = process.cwd(), explicitPath) {
+    if (explicitPath) {
+      const resolved = resolve3(explicitPath);
+      if (isUruProjectRoot(resolved)) {
+        return resolved;
+      }
+      return findNearestUruRoot(resolved);
+    }
+    return findNearestUruRoot(startDir);
+  },
+  async run(action, context) {
+    switch (action) {
+      case "setup":
+        return runSetup(context);
+      case "link":
+        return runLink(context);
+      case "configure":
+        return runConfigure(context);
+      case "install":
+        if ((context.options.platform ?? "macos") !== "macos") {
+          throw new Error("Only --platform macos is currently supported for Uru install.");
+        }
+        return installMacosApp(context);
+      case "migrate":
+        return runMigration(
+          context,
+          context.options.migrationAction ?? "push"
+        );
+    }
+  }
+};
+
+// src/apps/registry.ts
+var profiles = [uruProfile];
+function getAppProfile(appId) {
+  return profiles.find((profile) => profile.id === appId);
+}
+
+// src/apps/runAppCli.ts
+function assertAppCommand(options) {
+  if (!options.action || !options.app) {
+    throw new Error("Usage: polterbase app <setup|link|migrate|configure|install> <app>");
+  }
+}
+async function runAppCli(options) {
+  assertAppCommand(options);
+  const profile = getAppProfile(options.app);
+  if (!profile) {
+    throw new Error(`Unknown app profile: ${options.app}`);
+  }
+  const projectRoot = profile.resolveProjectRoot(process.cwd(), options.path);
+  process.stdout.write(
+    `${pc3.bold("Polterbase")} ${pc3.dim("app workflow")} ${pc3.bold(profile.displayName)} ${pc3.dim(`(${options.action})`)}
+
+`
+  );
+  return profile.run(options.action, {
+    cwd: process.cwd(),
+    projectRoot,
+    options
+  });
+}
+
 // src/index.tsx
-render(React8.createElement(App));
+async function main() {
+  const parsed = parseCliArgs(process.argv.slice(2));
+  if (parsed.mode === "help") {
+    printCliHelp();
+    return;
+  }
+  if (parsed.mode === "app") {
+    const exitCode = await runAppCli(parsed.options);
+    process.exit(exitCode);
+  }
+  render(React8.createElement(App));
+}
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${message}
+`);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polterware/polterbase",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "An interactive CLI for managing Supabase CLI workflows.",
   "type": "module",
   "bin": {