osx-query 0.1.2 → 0.1.4

package/README.md

@@ -1,21 +1,111 @@
 # osx-query
 
-Install:
+`osx-query` installs the native `osx` CLI for querying and interacting with macOS Accessibility trees.
+
+The npm package is a thin installer. During `npm i -g osx-query`, it downloads the signed and notarized binary that matches your Mac from the project's GitHub Releases.
+
+## Install
 
 ```bash
 npm i -g osx-query
 ```
 
-This package downloads the signed and notarized native `osx` CLI from the matching GitHub release for your macOS architecture.
+After install:
+
+```bash
+osx --help
+```
+
+## What You Get
+
+- CSS-like querying of Accessibility trees
+- Actions against matched elements
+- Interactive query mode for exploring app structure
+- Signed and notarized binaries for:
+  - macOS `arm64`
+  - macOS `x64`
 
-Example:
+## Examples
+
+Query the focused app:
 
 ```bash
 osx query --app focused "AXWindow AXButton"
 ```
 
-Supported platforms:
+Query a specific app:
+
+```bash
+osx query --app TextEdit "AXTextArea,AXTextField"
+```
+
+Open the interactive selector UI:
+
+```bash
+osx interactive TextEdit
+```
+
+## Requirements
+
+- macOS
+- Accessibility permission for the process running `osx`
+
+If queries return nothing useful, grant Accessibility access to your terminal app in:
+
+`System Settings -> Privacy & Security -> Accessibility`
+
+## Optional Codex Skill
+
+After install, the package can optionally prompt to run:
+
+```bash
+npx skills add Moulik-Budhiraja/OSX-Query
+```
+
+That step is optional and only appears in an interactive terminal. If you skip it during install, you can run it later yourself.
 
-- macOS `arm64`
-- macOS `x64`
+To suppress the prompt entirely:
 
+```bash
+OSX_QUERY_SKIP_SKILLS_PROMPT=1 npm i -g osx-query
+```
+
+## Troubleshooting
+
+If `npm i -g osx-query` succeeds but `osx` is not found, the usual cause is that your npm global bin directory is not on `PATH`.
+
+Check where npm installs global binaries:
+
+```bash
+npm prefix -g
+npm bin -g
+```
+
+Then make sure that bin directory is on your shell `PATH`.
+
+If `osx` exists but it is the wrong one, check for command shadowing:
+
+```bash
+which -a osx
+```
+
+That will show whether another `osx` binary or symlink is being found before the npm-installed one.
+
+If the command is found but macOS blocks it, verify the installed binary directly:
+
+```bash
+osx --help
+spctl -a -t exec -vv "$(which osx)"
+codesign -dv "$(which osx)" 2>&1 | head
+```
+
+If queries run but return nothing useful, the problem is usually Accessibility permissions, not installation. Grant access to your terminal in:
+
+`System Settings -> Privacy & Security -> Accessibility`
+
+If you want to reinstall cleanly:
+
+```bash
+npm uninstall -g osx-query
+npm i -g osx-query
+```

package/lib/install.js

@@ -4,6 +4,7 @@ const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
 const https = require("node:https");
+const readline = require("node:readline/promises");
 const { pipeline } = require("node:stream/promises");
 const { createWriteStream } = require("node:fs");
 const { spawnSync } = require("node:child_process");
@@ -87,12 +88,72 @@ function installBinary(extractedRoot, vendorDir) {
   fs.mkdirSync(vendorDir, { recursive: true });
   fs.copyFileSync(sourceBinary, targetBinary);
   fs.chmodSync(targetBinary, 0o755);
+  return targetBinary;
+}
+
+function shouldPromptForSkills() {
+  if (process.env.CI) {
+    return false;
+  }
+
+  if (process.env.OSX_QUERY_SKIP_SKILLS_PROMPT === "1") {
+    return false;
+  }
+
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+async function maybePromptForSkills() {
+  if (!shouldPromptForSkills()) {
+    console.log(
+      "Optional: run `npx skills add Moulik-Budhiraja/OSX-Query` to install the Codex skill."
+    );
+    return;
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    const answer = await rl.question(
+      "Install the optional Codex skill now? This will run `npx skills add Moulik-Budhiraja/OSX-Query` [y/N]: "
+    );
+
+    if (!/^(y|yes)$/i.test(answer.trim())) {
+      console.log(
+        "Skipped skill install. You can run `npx skills add Moulik-Budhiraja/OSX-Query` later."
+      );
+      return;
+    }
+  } finally {
+    rl.close();
+  }
+
+  const command = process.platform === "win32" ? "npx.cmd" : "npx";
+  const result = spawnSync(command, ["skills", "add", "Moulik-Budhiraja/OSX-Query"], {
+    stdio: "inherit",
+  });
+
+  if (result.error) {
+    console.warn(
+      "Skill installer could not be launched. Run `npx skills add Moulik-Budhiraja/OSX-Query` manually."
+    );
+    return;
+  }
+
+  if (result.status !== 0) {
+    console.warn(
+      "Skill install did not complete successfully. Run `npx skills add Moulik-Budhiraja/OSX-Query` manually."
+    );
+  }
 }
 
 async function main() {
-  const version = pkg.version;
-  const assetName = getAssetName(version);
-  const url = `https://github.com/Moulik-Budhiraja/OSX-Query/releases/download/v${version}/${assetName}`;
+  const binaryVersion = pkg.osxBinaryVersion || pkg.version;
+  const assetName = getAssetName(binaryVersion);
+  const url = `https://github.com/Moulik-Budhiraja/OSX-Query/releases/download/v${binaryVersion}/${assetName}`;
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "osx-query-"));
   const zipPath = path.join(tempDir, assetName);
   const extractDir = path.join(tempDir, "extract");
@@ -106,7 +167,10 @@ async function main() {
     fs.mkdirSync(extractDir, { recursive: true });
 
     extract(zipPath, extractDir);
-    installBinary(extractDir, vendorDir);
+    const installedBinary = installBinary(extractDir, vendorDir);
+    console.log(`Installed osx at ${installedBinary}`);
+    console.log("Run `osx --help` to get started.");
+    await maybePromptForSkills();
   } finally {
     fs.rmSync(tempDir, { recursive: true, force: true });
   }

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "osx-query",
-  "version": "0.1.2",
+  "version": "0.1.4",
+  "osxBinaryVersion": "0.1.2",
   "description": "macOS Accessibility query CLI",
   "license": "MIT",
   "repository": {