ask-pro 0.1.0

package/scripts/refresh-local-plugin.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const args = parseArgs(process.argv.slice(2));
+const pluginName = args.pluginName ?? "ask-pro";
+const codexHome = args.codexHome ?? process.env.CODEX_HOME ?? path.join(os.homedir(), ".codex");
+const marketplacePath = args.marketplacePath ?? (await findCodexMarketplace(codexHome, pluginName));
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(scriptDir, "..");
+const marketplaceFile = path.resolve(marketplacePath);
+const marketplace = JSON.parse(await fs.readFile(marketplaceFile, "utf8"));
+const marketplaceName = String(marketplace.name ?? "").trim();
+if (!marketplaceName) {
+  throw new Error("Marketplace file must include a top-level name.");
+}
+
+const plugin = Array.isArray(marketplace.plugins)
+  ? marketplace.plugins.find((entry) => entry?.name === pluginName)
+  : null;
+if (!plugin) {
+  throw new Error(`Plugin '${pluginName}' was not found in ${marketplaceFile}.`);
+}
+if (plugin.source?.source === "local") {
+  const configuredSourcePath = plugin.source?.path;
+  if (typeof configuredSourcePath !== "string" || !configuredSourcePath.trim()) {
+    throw new Error(`Plugin '${pluginName}' local source must include a path.`);
+  }
+  const configuredSourceRoot = resolveConfiguredSourceRoot(configuredSourcePath, marketplaceFile);
+  if (!samePath(configuredSourceRoot, repoRoot)) {
+    throw new Error(
+      `Plugin '${pluginName}' marketplace path resolves to ${configuredSourceRoot}, not this checkout ${repoRoot}.`,
+    );
+  }
+} else if (plugin.source?.source !== "url") {
+  throw new Error(`Plugin '${pluginName}' must come from a local or URL marketplace source.`);
+}
+
+const manifestPath = path.join(repoRoot, ".codex-plugin", "plugin.json");
+const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+if (manifest.name !== pluginName) {
+  throw new Error(
+    `Plugin manifest name '${manifest.name}' does not match requested plugin '${pluginName}'.`,
+  );
+}
+
+const cacheRoot = path.resolve(codexHome, "plugins", "cache");
+const pluginCacheRoot = path.resolve(cacheRoot, marketplaceName, pluginName);
+const cacheVersion = plugin.source?.source === "local" ? "local" : manifest.version;
+if (typeof cacheVersion !== "string" || !cacheVersion.trim()) {
+  throw new Error(`Plugin '${pluginName}' manifest must include a version.`);
+}
+const targetRoot = path.resolve(pluginCacheRoot, cacheVersion);
+assertInside(
+  pluginCacheRoot,
+  cacheRoot,
+  "Resolved plugin cache path is outside Codex plugin cache",
+);
+
+const requiredDistEntry = path.join(repoRoot, "dist", "bin", "ask-pro-cli.js");
+if (!(await exists(requiredDistEntry))) {
+  throw new Error("dist is missing. Run `pnpm run build` before refreshing the plugin cache.");
+}
+const repoNodeModules = path.join(repoRoot, "node_modules");
+if (!(await exists(repoNodeModules))) {
+  throw new Error(
+    "node_modules is missing. Run `pnpm install` before refreshing the plugin cache.",
+  );
+}
+
+await removeNodeModulesLink(path.join(targetRoot, "node_modules"));
+await fs.rm(targetRoot, { recursive: true, force: true });
+await fs.mkdir(targetRoot, { recursive: true });
+
+for (const item of [
+  ".codex-plugin",
+  "assets",
+  "skills",
+  "references",
+  "README.md",
+  "LICENSE",
+  "package.json",
+  "pnpm-lock.yaml",
+  "pnpm-workspace.yaml",
+  "dist",
+]) {
+  const source = path.join(repoRoot, item);
+  if (!(await exists(source))) continue;
+  await fs.cp(source, path.join(targetRoot, item), { recursive: true, force: true });
+}
+
+await fs.mkdir(path.join(targetRoot, "scripts"), { recursive: true });
+await fs.cp(
+  path.join(repoRoot, "scripts", "run-cached-cli.mjs"),
+  path.join(targetRoot, "scripts", "run-cached-cli.mjs"),
+  { force: true },
+);
+await fs.symlink(repoNodeModules, path.join(targetRoot, "node_modules"), "junction");
+
+console.log("Refreshed local Codex plugin cache:");
+console.log(`  source: ${repoRoot}`);
+console.log(`  target: ${targetRoot}`);
+console.log("");
+console.log("Restart or reload Codex to pick up refreshed plugin skills.");
+
+function parseArgs(argv) {
+  const result = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const value = argv[i + 1];
+    if (!arg.startsWith("--") || !value || value.startsWith("--")) {
+      throw new Error(`Expected --name value argument, got '${arg}'.`);
+    }
+    i += 1;
+    if (arg === "--marketplace-path") result.marketplacePath = value;
+    else if (arg === "--codex-home") result.codexHome = value;
+    else if (arg === "--plugin-name") result.pluginName = value;
+    else throw new Error(`Unknown argument '${arg}'.`);
+  }
+  return result;
+}
+
+function assertInside(child, parent, message) {
+  const relative = path.relative(parent, child);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`${message}: ${child}`);
+  }
+}
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function removeNodeModulesLink(filePath) {
+  try {
+    const stat = await fs.lstat(filePath);
+    if (stat.isSymbolicLink()) {
+      await fs.unlink(filePath);
+    }
+  } catch {
+    // Missing or non-removable links are handled by the full target cleanup.
+  }
+}
+
+async function findCodexMarketplace(codexHome, pluginName) {
+  const codexMarketplace = path.join(
+    codexHome,
+    ".tmp",
+    "marketplaces",
+    pluginName,
+    ".agents",
+    "plugins",
+    "marketplace.json",
+  );
+  if (await exists(codexMarketplace)) return codexMarketplace;
+  return path.join(os.homedir(), ".agents", "plugins", "marketplace.json");
+}
+
+function resolveConfiguredSourceRoot(sourcePath, marketplaceFile) {
+  const candidates = [
+    path.resolve(path.dirname(marketplaceFile), sourcePath),
+    path.resolve(os.homedir(), sourcePath),
+  ];
+  return candidates.find((candidate) => samePath(candidate, repoRoot)) ?? candidates[0];
+}
+
+function samePath(left, right) {
+  const a = path.resolve(left);
+  const b = path.resolve(right);
+  return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+}

package/scripts/refresh-local-plugin.ps1

@@ -0,0 +1,93 @@
+param(
+  [string]$MarketplacePath = "",
+  [string]$CodexHome = $(if ($env:CODEX_HOME) { $env:CODEX_HOME } else { "$HOME/.codex" }),
+  [string]$PluginName = "ask-pro"
+)
+
+$ErrorActionPreference = "Stop"
+
+function Resolve-StrictPath([string]$Path) {
+  return [System.IO.Path]::GetFullPath((Resolve-Path -LiteralPath $Path).Path)
+}
+
+function Join-And-Normalize([string]$Base, [string[]]$Parts) {
+  return [System.IO.Path]::GetFullPath((Join-Path -Path $Base -ChildPath ([System.IO.Path]::Combine($Parts))))
+}
+
+$repoRoot = Resolve-StrictPath (Join-Path $PSScriptRoot "..")
+if ([string]::IsNullOrWhiteSpace($MarketplacePath)) {
+  $codexMarketplace = Join-And-Normalize $CodexHome @(".tmp", "marketplaces", $PluginName, ".agents", "plugins", "marketplace.json")
+  if (Test-Path -LiteralPath $codexMarketplace) {
+    $MarketplacePath = $codexMarketplace
+  } else {
+    $MarketplacePath = "$HOME/.agents/plugins/marketplace.json"
+  }
+}
+$marketplaceFile = Resolve-StrictPath $MarketplacePath
+$marketplace = Get-Content -LiteralPath $marketplaceFile -Raw | ConvertFrom-Json
+$marketplaceName = [string]$marketplace.name
+if ([string]::IsNullOrWhiteSpace($marketplaceName)) {
+  throw "Marketplace file must include a top-level name."
+}
+
+$plugin = @($marketplace.plugins) | Where-Object { $_.name -eq $PluginName } | Select-Object -First 1
+if (-not $plugin) {
+  throw "Plugin '$PluginName' was not found in $marketplaceFile."
+}
+if (($plugin.source.source -ne "local") -and ($plugin.source.source -ne "url")) {
+  throw "Plugin '$PluginName' must come from a local or URL marketplace source."
+}
+
+$sourceRoot = Resolve-StrictPath $repoRoot
+$manifestPath = Join-Path $sourceRoot ".codex-plugin/plugin.json"
+if (-not (Test-Path -LiteralPath $manifestPath)) {
+  throw "Missing plugin manifest at $manifestPath."
+}
+
+$manifest = Get-Content -LiteralPath $manifestPath -Raw | ConvertFrom-Json
+if ($manifest.name -ne $PluginName) {
+  throw "Plugin manifest name '$($manifest.name)' does not match requested plugin '$PluginName'."
+}
+
+$codexHomePath = [System.IO.Path]::GetFullPath($CodexHome)
+$cacheRoot = Join-And-Normalize $codexHomePath @("plugins", "cache")
+$pluginCacheRoot = Join-And-Normalize $cacheRoot @($marketplaceName, $PluginName)
+$cacheVersion = $(if ($plugin.source.source -eq "local") { "local" } else { [string]$manifest.version })
+if ([string]::IsNullOrWhiteSpace($cacheVersion)) {
+  throw "Plugin '$PluginName' manifest must include a version."
+}
+$targetRoot = Join-And-Normalize $pluginCacheRoot @($cacheVersion)
+
+$cacheRootWithSeparator = $cacheRoot.TrimEnd([System.IO.Path]::DirectorySeparatorChar, [System.IO.Path]::AltDirectorySeparatorChar) + [System.IO.Path]::DirectorySeparatorChar
+if (-not $pluginCacheRoot.StartsWith($cacheRootWithSeparator, [System.StringComparison]::OrdinalIgnoreCase)) {
+  throw "Resolved plugin cache path is outside Codex plugin cache: $pluginCacheRoot"
+}
+
+if (Test-Path -LiteralPath $targetRoot) {
+  Remove-Item -LiteralPath $targetRoot -Recurse -Force
+}
+New-Item -ItemType Directory -Path $targetRoot -Force | Out-Null
+
+$itemsToCopy = @(
+  ".codex-plugin",
+  "skills",
+  "references",
+  "README.md",
+  "LICENSE",
+  "package.json",
+  "dist"
+)
+
+foreach ($item in $itemsToCopy) {
+  $source = Join-Path $sourceRoot $item
+  if (-not (Test-Path -LiteralPath $source)) {
+    continue
+  }
+  Copy-Item -LiteralPath $source -Destination $targetRoot -Recurse -Force
+}
+
+Write-Host "Refreshed local Codex plugin cache:"
+Write-Host "  source: $sourceRoot"
+Write-Host "  target: $targetRoot"
+Write-Host ""
+Write-Host "Restart or reload Codex to pick up refreshed plugin skills."

package/skills/ask-pro/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: ask-pro
+description: Escalate hard engineering questions to ChatGPT Pro through browser automation with focused repo context. Use when an agent needs a stronger external review, architecture plan, migration strategy, production-debugging second opinion, or when the user explicitly asks to use $ask-pro.
+---
+
+# $ask-pro
+
+Use `$ask-pro` to ask ChatGPT Pro for a focused second opinion on hard engineering work.
+
+The calling agent still owns the work. Use Pro for judgment, architecture, risk review, or implementation planning when the decision is consequential enough to justify a browser run.
+
+## Trigger
+
+Use this skill when the user explicitly asks for `$ask-pro`, or when a second opinion would materially reduce risk for:
+
+- backend architecture
+- schema or data migrations
+- auth, sessions, permissions, or billing
+- queues, workers, idempotency, caching, scaling, or latency
+- production debugging and observability
+- ambiguous implementation paths where a second opinion would reduce risk
+
+Do not use it for trivial syntax fixes, formatting, obvious dependency updates, or small bugs with a clear cause.
+
+## Critical Reminders
+
+- Long waits are normal. ask-pro can take a super long time to run; do not
+  close or kill the browser window/run until at least 3 hours have passed unless
+  the CLI has completed, failed, or explicitly asks for human action.
+
+## Workflow
+
+When invoked:
+
+1. Inspect the repo and the relevant files.
+2. Identify the exact decision Pro should answer.
+3. Choose a small, high-signal file bundle with `--files`.
+4. Write the prompt yourself using the Prompt Shape below.
+5. Run the smallest useful command, usually
+   `ask-pro --no-temporary --files "<glob>" "<prompt>"` for repo advisories.
+   For multiline prompts, write a temporary prompt file and use
+   `ask-pro --no-temporary --prompt-file <path> --files "<glob>"`; do not rely
+   on shell multiline quoting.
+   If installed through the skills CLI and `ask-pro` is not on `PATH`, install
+   the standalone CLI from the [README](https://github.com/JJLiebig/ask-pro#skills-cli-codex-and-other-supported-agents)
+   first. For Codex plugin installs without `ask-pro` on `PATH`, use the cached
+   plugin runner. Locate it under the installed plugin cache,
+   usually
+   `~/.codex/plugins/cache/<marketplace-name>/ask-pro/<version>/scripts/run-cached-cli.mjs`,
+   then call it with:
+   `node <cached-runner> -- --cwd <target-repo-root> --no-temporary --prompt-file <path> --files "<repo-relative-glob>"`.
+   On Git marketplace installs, the first cached-runner call may bootstrap the
+   content-addressed runtime under `$CODEX_HOME/plugin-runtimes/ask-pro/` by
+   installing dependencies and building `dist`; wait for that to finish. The
+   installed plugin cache stays immutable.
+6. If auth is required, stop and ask the human to log in in the opened browser.
+7. Read the CLI's compact `ask_pro` record and run the emitted `resume` or
+   `harvest` command when that is the next action.
+8. Treat the answer as advisory; turn it into your own plan before editing code.
+
+`ask-pro` selects `Latest`, then `Pro` intelligence. Do not require a
+different dated model label or a separate thinking-effort control in the prompt
+or workflow.
+
+Fresh runs try ChatGPT Temporary Chat by default and automatically fall back to
+normal ChatGPT if the current account/UI does not expose Pro there. For repo
+advisories, large bundles, review rounds, or anything where recovery matters,
+prefer `--no-temporary` from the start. Add `--temporary` only when Temporary
+Chat is required and falling back would be wrong. Temporary Chat is less
+recoverable after browser/tab loss.
+
+On Windows, ordinary managed Chrome runs start minimized. First login,
+resume/recovery, and stale-auth paths stay visible or are restored for human
+action. Local managed Chrome guards browser input while Pro is answering.
+If login, MFA, a browser challenge, or incomplete-answer debugging needs human
+attention, ask-pro should restore or retain the browser and emit the next
+action.
+
+Do not set `ASK_PRO_AGENT_ID` for ordinary or concurrent use; the shared
+`ask-pro` browser profile under `$CODEX_HOME/state/ask-pro/` handles concurrent
+agents automatically. Set `ASK_PRO_AGENT_ID` only when explicitly testing an
+isolated profile or when the human requests a separate browser login. Use a
+stable reusable lowercase id like `review-t1`, not a one-off task slug, because
+each new id creates a new Chrome profile and may require the human to log in
+again. Example:
+`ASK_PRO_AGENT_ID=review-t1 ask-pro ...`.
+
+## Prompt Shape
+
+Assume Pro has no caller or repository context. Include each material fact and
+instruction once: the goal, current state, hard constraints, evidence, success
+criteria, and required output. Do not rely on the agent's conversation context, repo
+folklore, prior ask-pro runs, branch names, or unstated user preferences.
+Keep advisory design consults as plain answer requests. Start advisory prompts
+with:
+
+```text
+Return final Markdown only, with no preamble or implementation package.
+```
+
+The CLI wrapper already tells Pro to read `CONTEXT.zip` and call out missing or
+conflicting context. Do not repeat that instruction. Add task-specific output
+requirements only when needed. For risk or review work, ask Pro to rank
+findings by severity. For architecture or design consults, ask directly for the
+recommendation and tradeoffs.
+
+Use `--artifacts` only when the standard implementation package is needed. The
+wrapper supplies the zip name, standard files, and markdown fallback; add only
+task-specific deliverables not covered by that package. Keep advisory consults
+inline by default.
+Keep bundles focused: source files under review, focused tests, relevant docs,
+known recent changes, and validation status. Avoid whole-repo bundles unless the
+question is explicitly architectural.
+
+## Output
+
+Normal `ask-pro` stdout is compact TOON-style telemetry. Use `state`, `action`,
+`resume`, and `harvest` to decide the next command. Browser progress may appear
+on stderr and can be ignored unless diagnosing a stuck run.
+
+When present, use `profile`, `profile_path`, `chrome`, and `language` only as
+diagnostic hints. They tell you whether the run used the shared profile, an
+isolated agent profile, saved DevTools state, and English browser steering.
+When present, `conversation_url` is a recoverable non-temporary ChatGPT
+conversation URL.
+
+`ask-pro --harvest <session-id>` prints the raw markdown answer only for
+answer-bearing states such as `COMPLETED` or `HARVESTED`.
+For pending/incomplete sessions it prints compact status/action instead. For
+sessions run with `--artifacts`, any provided `ask-pro-response.zip` is
+extracted under the session's `pro-output/` directory and described in
+`PRO_OUTPUT_MANIFEST.json`. Inline-default sessions should not expect a zip.
+
+`INCOMPLETE_ANSWER` / `stopped_without_answer` means ChatGPT stopped without
+an answer after ask-pro attempted one automatic `continue`. Present the caller
+with the emitted resume command or a full retry of the original request in a new
+chat, and wait for their choice. Do not automatically resume or retry this state.
+An explicit `--resume` allows one more continuation attempt.
+
+`COMPLETED` means harvest now; the run browser may already be closed. If the
+state is `INCOMPLETE_ANSWER` / `preamble_without_artifacts`, do not treat
+`ANSWER.md` as final. Try resume/harvest if recoverable; otherwise rerun with
+`--no-temporary`, a tighter bundle, and a more direct prompt.
+
+## Commands
+
+```bash
+ask-pro "Review the async billing webhook migration plan and return an implementation plan."
+ask-pro --no-temporary --prompt-file question.md --files src --files tests
+ask-pro --temporary "Review this sensitive migration plan, and fail if Temporary Chat cannot use Pro."
+ask-pro --no-temporary "Review this in normal ChatGPT instead of Temporary Chat."
+ask-pro --prompt-file question.md --files .\src
+ask-pro --artifacts --prompt-file implementation-plan.md --files src
+ask-pro --files "src/api/stripe/**" --files "prisma/**" --files "src/lib/billing/**" \
+  "Review whether this Stripe webhook flow should use a queue or transactional outbox."
+ask-pro --dry-run "Prepare the Pro handoff but do not open the browser."
+ask-pro --resume <session-id>
+ask-pro --harvest <session-id>
+```
+
+If the binary is not on `PATH`, skills CLI installs need the standalone CLI from
+the README. Codex plugin installs can use the cached plugin runner. Do not run
+the plugin from a mutable development checkout; it may contain in-flight changes
+that have not been synced for agents.
+
+```bash
+node <cached-runner> -- --cwd /path/to/repo --no-temporary --prompt-file question.md --files src
+```
+
+In cached-runner fallback mode, `--files` must be inside `--cwd`. Use
+repo-relative `--files`; do not point at files outside the target repo cwd.
+
+## Safety
+
+Never ask for, read, store, type, or log passwords, MFA codes, recovery codes, session cookies, or raw auth tokens.
+
+Browser auth is human-controlled. Continue only after the human says the ChatGPT composer is visible.
+
+After submit, avoid interacting with any retained Chrome run window while Pro is
+thinking. ask-pro guards input after submit, but the safest agent behavior is to
+let the run finish or resume/harvest from CLI telemetry.