@userreason/wizard 0.1.0 → 0.2.0

package/dist/chunk-HACTNBV3.js

@@ -0,0 +1,51 @@
+import { createRequire as createWizardRequire } from 'node:module'; import { fileURLToPath as wizardFileURLToPath } from 'node:url'; import { dirname as wizardDirname } from 'node:path'; const require = createWizardRequire(import.meta.url); const __filename = wizardFileURLToPath(import.meta.url); const __dirname = wizardDirname(__filename);
+import {
+  Cancelled,
+  openBrowser
+} from "./chunk-SJVLAYGG.js";
+import {
+  authorizeCli,
+  grantSummary,
+  printable,
+  resolveCredentials,
+  saveConfig
+} from "./chunk-GGARVSPT.js";
+
+// src/cli-access.ts
+async function offerCliAccess(config, terminal, options) {
+  if (!options.installed || options.skip || !terminal.interactive && !options.requested) return { status: "skipped" };
+  if (options.preview !== false) terminal.note("Connect the project CLI for ongoing work. The browser lets you choose workspaces and permissions; all current and future workspaces and available permissions are selected initially. Your workspace role still limits every action. This is separate from the short installation approval.", "Ongoing CLI access");
+  let waiting;
+  try {
+    if (!options.requested && !await terminal.confirm("Connect the CLI for ongoing use?", true, { recommended: true })) return { status: "declined" };
+    let signedIn = false;
+    const show = async (url, label, previous) => {
+      const opened = !options.noOpen && await openBrowser(url);
+      waiting?.stop(previous);
+      waiting = terminal.waiting(label, opened ? {} : { link: url });
+    };
+    const result = await authorizeCli(config, resolveCredentials(config), {
+      onDevice: (device) => {
+        signedIn = true;
+        return show(device.verificationUriComplete, `Sign in for the CLI ${terminal.kit.S.dot} ${terminal.kit.c.muted("code")} ${terminal.kit.c.code(device.userCode)}`);
+      },
+      onApproval: (request) => show(request.approval_url, "Review and approve CLI access in the browser", signedIn ? "Signed in" : void 0)
+    });
+    waiting?.stop();
+    await saveConfig(config, options.development);
+    const grant = "grant" in result ? result.grant : void 0;
+    const summary = grantSummary(grant);
+    terminal.success(`CLI access approved${summary ? ` ${terminal.kit.c.muted(`(${summary})`)}` : ""}`);
+    return { status: "approved", grant };
+  } catch (error) {
+    waiting?.stop();
+    if (error instanceof Cancelled) return { status: "declined" };
+    if (error instanceof Error) terminal.warn(printable(error.message));
+    terminal.warn("The application is installed, but ongoing CLI access was not connected. Run the project CLI with login --open to finish.");
+    return { status: "failed" };
+  }
+}
+
+export {
+  offerCliAccess
+};

package/dist/chunk-JD5U4U26.js

@@ -0,0 +1,125 @@
+import { createRequire as createWizardRequire } from 'node:module'; import { fileURLToPath as wizardFileURLToPath } from 'node:url'; import { dirname as wizardDirname } from 'node:path'; const require = createWizardRequire(import.meta.url); const __filename = wizardFileURLToPath(import.meta.url); const __dirname = wizardDirname(__filename);
+import {
+  Cancelled
+} from "./chunk-SJVLAYGG.js";
+import {
+  cliCommand,
+  compatibleCliVersion
+} from "./chunk-YMSGDC4B.js";
+import {
+  packageProfile
+} from "./chunk-GGARVSPT.js";
+
+// src/global-cli.ts
+import { execFile } from "node:child_process";
+import { constants } from "node:fs";
+import { access, mkdtemp, readFile, realpath, rm } from "node:fs/promises";
+import { delimiter, dirname, join, resolve } from "node:path";
+import { promisify } from "node:util";
+var run = promisify(execFile);
+var registry = (profile) => profile.kind === "local-development" ? profile.registry : "https://registry.npmjs.org";
+var registryArgs = (profile) => [`--registry=${registry(profile)}`, `--@userreason:registry=${registry(profile)}`];
+var installArgs = (profile) => ["install", "--global", "--ignore-scripts", `@userreason/cli@${profile.cliVersion}`, ...registryArgs(profile)];
+function globalCliInstallCommand(profile = packageProfile()) {
+  return ["npm", ...installArgs(profile)].join(" ");
+}
+async function installedCli(directory) {
+  const { stdout } = await run("npm", ["root", "--global"], { cwd: directory, timeout: 15e3, maxBuffer: 64e3 });
+  const root = stdout.trim();
+  if (!root) throw new Error("npm did not report its global package directory.");
+  try {
+    const manifest = JSON.parse(await readFile(join(root, "@userreason/cli/package.json"), "utf8"));
+    if (manifest.name !== "@userreason/cli" || typeof manifest.version !== "string") throw new Error("Invalid global CLI package.");
+    return { root, version: manifest.version };
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  }
+}
+async function commandAvailable(root, projectDirectory) {
+  const windows = process.platform === "win32";
+  const expected = await realpath(windows ? join(dirname(root), "userreason.cmd") : join(root, "@userreason/cli/dist/bin.js"));
+  let projectCommand;
+  try {
+    projectCommand = await realpath(join(projectDirectory, windows ? "node_modules/.bin/userreason.cmd" : "node_modules/@userreason/cli/dist/bin.js"));
+  } catch {
+  }
+  const names = windows ? ["userreason.com", "userreason.exe", "userreason.bat", "userreason.cmd"] : ["userreason"];
+  for (const directory of (process.env.PATH ?? "").split(delimiter)) {
+    if (!directory || resolve(directory) !== directory) continue;
+    for (const name of names) {
+      const candidate = join(directory, name);
+      try {
+        await access(candidate, windows ? constants.F_OK : constants.X_OK);
+        const target = await realpath(candidate);
+        if (target === projectCommand) continue;
+        return target === expected;
+      } catch {
+      }
+    }
+  }
+  return false;
+}
+async function offerGlobalCli(project, terminal, options) {
+  if (!options.installed || options.skip || !terminal.interactive && !options.requested) return { status: "skipped" };
+  const profile = options.profile ?? packageProfile();
+  const command = globalCliInstallCommand(profile);
+  if (options.preview !== false) terminal.note(`Make the userreason command available across your projects. The project keeps its own CLI for teammates and agents.${profile.kind === "local-development" ? `
+This installs development CLI ${profile.cliVersion} from ${profile.registry}, replacing the CLI in npm's current global prefix. Its default API and documentation are development.` : ""}`, "Optional global CLI");
+  let cache;
+  try {
+    if (!options.requested && !await terminal.confirm("Make userreason available across your projects?", true)) return { status: "declined" };
+    let installed = await installedCli(project.directory);
+    const reuse = installed && compatibleCliVersion(installed.version, profile) && !options.force;
+    if (!reuse) {
+      cache = await mkdtemp(join(await realpath(project.directory), ".userreason-npm-"));
+      await terminal.task("Installing the global UserReason CLI", async () => {
+        try {
+          const child = run("npm", [...installArgs(profile), "--cache", cache], {
+            cwd: project.directory,
+            timeout: 12e4,
+            maxBuffer: 4e6,
+            env: { ...process.env, npm_config_cache: cache, NPM_CONFIG_CACHE: cache, npm_config_ignore_scripts: "true" }
+          });
+          if (options.verbose) {
+            child.child.stdout?.on("data", (chunk) => process.stderr.write(chunk));
+            child.child.stderr?.on("data", (chunk) => process.stderr.write(chunk));
+          }
+          await child;
+        } catch {
+          throw new Error("Global CLI installation failed. Check npm permissions or rerun with --debug; project setup is complete.");
+        }
+      }, "Global CLI installed");
+      installed = await installedCli(project.directory);
+    }
+    if (!installed || !compatibleCliVersion(installed.version, profile)) throw new Error("npm did not install the required global CLI version.");
+    let available = false;
+    try {
+      available = await commandAvailable(installed.root, project.directory);
+    } catch {
+    }
+    if (reuse) terminal.success(`Global CLI ${installed.version} is already installed`);
+    if (!available) terminal.warn(`Global CLI ${installed.version} is installed, but this terminal does not resolve userreason to it. Check npm's global bin directory in PATH and restart your terminal or agent. Use ${cliCommand(project)} in this project meanwhile.`);
+    return { status: reuse ? "already_present" : "installed", version: installed.version, command_available: available };
+  } catch (error) {
+    if (error instanceof Cancelled) return { status: "declined" };
+    terminal.warn(`The optional global CLI could not be set up. ${error instanceof Error ? error.message : ""}`);
+    terminal.note(`${command}
+
+The project CLI remains available: ${cliCommand(project)}`, "Install globally later");
+    return { status: "failed", install_command: command };
+  } finally {
+    if (cache) {
+      try {
+        await rm(cache, { recursive: true, force: true });
+      } catch {
+        terminal.warn("Unable to remove the temporary .userreason-npm-* cache inside your project.");
+      }
+    }
+  }
+}
+
+export {
+  globalCliInstallCommand,
+  offerGlobalCli
+};

package/dist/chunk-KV6GSBTQ.js

@@ -0,0 +1,165 @@
+import { createRequire as createWizardRequire } from 'node:module'; import { fileURLToPath as wizardFileURLToPath } from 'node:url'; import { dirname as wizardDirname } from 'node:path'; const require = createWizardRequire(import.meta.url); const __filename = wizardFileURLToPath(import.meta.url); const __dirname = wizardDirname(__filename);
+import {
+  Cancelled
+} from "./chunk-SJVLAYGG.js";
+import {
+  initializationPath
+} from "./chunk-6DCCEVPD.js";
+import {
+  cliCommand
+} from "./chunk-YMSGDC4B.js";
+import {
+  packageProfile
+} from "./chunk-GGARVSPT.js";
+
+// src/agent-note.ts
+import { constants } from "node:fs";
+import { lstat, stat, readFile, open } from "node:fs/promises";
+import { join, relative } from "node:path";
+var start = "<!-- userreason:feedback:start -->";
+var end = "<!-- userreason:feedback:end -->";
+function note(entry, docs) {
+  return `## User feedback
+
+When investigating low conversion, drop-off, adoption or unclear user needs,
+consider targeted in-app feedback alongside analytics to understand users' reasons.
+This project collects feedback through \`@userreason/js\`, initialized in \`${entry}\`.
+See [feedback documentation](${docs}).`;
+}
+function earlierNotes(entry) {
+  const previousReference = '\nFor SDK methods, prompt settings and CLI commands, read the current documentation instead of relying on memory:\n`npx -y @userreason/cli@latest docs search "<question>"`, or https://docs.userreason.com/llms.txt.';
+  return [
+    `## User feedback
+
+This project uses \`@userreason/js\` to collect in-app user feedback,
+initialized in \`${entry}\`. See [SDK documentation](node_modules/@userreason/js/README.md).`,
+    note(entry, "node_modules/@userreason/js/FEEDBACK.md"),
+    note(entry, "node_modules/@userreason/js/README.md"),
+    ...["FEEDBACK.md", "README.md"].map((file) => note(entry, `node_modules/@userreason/js/${file}`) + previousReference)
+  ];
+}
+async function planAgentNote(project, options = {}) {
+  let path = "", file = "", metadata;
+  for (const candidate of ["AGENTS.md", "CLAUDE.md"]) {
+    try {
+      metadata = await lstat(join(project.directory, candidate));
+    } catch (error) {
+      if (error.code === "ENOENT") continue;
+      throw error;
+    }
+    path = join(project.directory, candidate);
+    file = candidate;
+    break;
+  }
+  if (!metadata) return { status: "skipped", reason: "no_guidance_file" };
+  if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.nlink !== 1 || metadata.size > 1e6)
+    return { status: "skipped", file, reason: "guidance_file_needs_review" };
+  const before = await readFile(path, "utf8");
+  const headings = [...before.matchAll(/^## User feedback[ \t]*\r?$/gm)];
+  if (headings.length > 1) return { status: "skipped", file, reason: "existing_feedback_section" };
+  const heading = headings[0];
+  let replacement;
+  if (heading) {
+    let offset = heading.index;
+    const remainder = before.slice(offset + heading[0].length);
+    const nextHeading = /^#{1,2}[ \t]/m.exec(remainder);
+    const until = nextHeading ? offset + heading[0].length + nextHeading.index : before.length;
+    const section = before.slice(offset, until).replaceAll("\r\n", "\n");
+    const marked = before.slice(0, offset).endsWith(start + (before.includes("\r\n") ? "\r\n" : "\n"));
+    const body = marked ? section.replace(new RegExp(`\\n${end}\\n*$`), "") : section;
+    const oldEntry = /initialized in `([^`\n]+)`\./.exec(body)?.[1];
+    if (!oldEntry || !earlierNotes(oldEntry).includes(body.trimEnd()) || marked && (before.split(start).length !== 2 || before.split(end).length !== 2) || !marked && (before.includes(start) || before.includes(end)))
+      return { status: section.includes("@userreason/js") ? "already_present" : "skipped", file, reason: "existing_feedback_section" };
+    if (marked) offset -= start.length + (before.includes("\r\n") ? 2 : 1);
+    replacement = { offset, previous: before.slice(offset, until), after: "" };
+  } else if (before.includes(start) || before.includes(end)) return { status: "already_present", file };
+  if (options.beforeInstall) return { path, file, before, snippet: "", addition: "", dev: metadata.dev, ino: metadata.ino, ...replacement ? { replacement } : {} };
+  const source = await initializationPath(project);
+  if (!source) return { status: "skipped", file, reason: "no_initialization" };
+  const entry = relative(project.directory, source).replaceAll("\\", "/");
+  if (!entry || entry.startsWith("../") || /[\r\n`]/.test(entry))
+    return { status: "skipped", file, reason: "initialization_path_needs_review" };
+  let docs = "node_modules/@userreason/js/FEEDBACK.md";
+  try {
+    if (!(await stat(join(project.directory, docs))).isFile()) docs = "node_modules/@userreason/js/README.md";
+  } catch (error) {
+    if (error.code === "ENOENT") docs = "node_modules/@userreason/js/README.md";
+    else throw error;
+  }
+  try {
+    if (!(await stat(join(project.directory, docs))).isFile()) return { status: "skipped", file, reason: "docs_unavailable" };
+  } catch (error) {
+    if (error.code === "ENOENT") return { status: "skipped", file, reason: "docs_unavailable" };
+    throw error;
+  }
+  const snippet = note(entry, docs) + `
+For SDK methods, survey settings and CLI commands, read the current documentation instead of relying on memory:
+\`${cliCommand(project)} docs search "<question>"\`, or ${packageProfile().docsUrl}/llms.txt.`;
+  const newline = before.includes("\r\n") ? "\r\n" : "\n";
+  const separator = before.length ? before.endsWith(newline + newline) ? "" : before.endsWith(newline) ? newline : newline + newline : "";
+  const addition = separator + `${snippet}
+`.replaceAll("\n", newline);
+  if (replacement) {
+    const trailing = /(?:\r?\n)*$/.exec(replacement.previous)[0];
+    replacement.after = snippet.replaceAll("\n", newline) + (trailing || newline);
+  }
+  return { path, file, before, snippet, addition, dev: metadata.dev, ino: metadata.ino, ...replacement ? { replacement } : {} };
+}
+async function applyAgentNote(plan) {
+  if ((await lstat(plan.path)).isSymbolicLink()) throw new Error("The guidance file became a symlink.");
+  const handle = await open(plan.path, constants.O_RDWR | (plan.replacement ? 0 : constants.O_APPEND) | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const metadata = await handle.stat();
+    if (!metadata.isFile() || metadata.nlink !== 1 || metadata.dev !== plan.dev || metadata.ino !== plan.ino || await handle.readFile("utf8") !== plan.before)
+      throw new Error("The guidance file changed after the preview.");
+    if (plan.replacement) {
+      const { offset, previous, after } = plan.replacement;
+      const position = Buffer.byteLength(plan.before.slice(0, offset));
+      const tail = Buffer.from(after + plan.before.slice(offset + previous.length));
+      let written = 0;
+      while (written < tail.length) {
+        const result = await handle.write(tail, written, tail.length - written, position + written);
+        if (!result.bytesWritten) throw new Error("Unable to update the feedback note.");
+        written += result.bytesWritten;
+      }
+      await handle.truncate(position + tail.length);
+    } else await handle.appendFile(plan.addition, "utf8");
+  } finally {
+    await handle.close();
+  }
+}
+async function offerAgentNote(project, terminal, options) {
+  if (!options.installed || options.skip || !terminal.interactive && !options.requested)
+    return { status: "skipped", reason: options.installed ? "not_requested" : "installation_pending" };
+  try {
+    const plan = await planAgentNote(project);
+    if (!("path" in plan)) {
+      if (plan.status === "already_present") terminal.info(`User feedback note already present in ${plan.file}`);
+      else if (plan.file || options.requested) terminal.info("No user feedback note added. An existing guidance file, SDK initialization and local SDK documentation are required; existing feedback sections are preserved.");
+      return plan;
+    }
+    if (options.preview !== false) terminal.note(
+      plan.replacement ? `Current note:
+${plan.replacement.previous.trim()}
+
+Proposed note:
+${plan.snippet}` : plan.snippet,
+      `Optional ${plan.replacement ? "update" : "addition"} to ${plan.file}`
+    );
+    if (!options.requested && !await terminal.confirm(`${plan.replacement ? "Update" : "Add"} this user feedback note ${plan.replacement ? "in" : "to"} ${plan.file}?`, true, { recommended: true }))
+      return { status: "declined", file: plan.file };
+    await applyAgentNote(plan);
+    terminal.success(`User feedback note ${plan.replacement ? "updated in" : "added to"} ${plan.file}`);
+    return { status: plan.replacement ? "updated" : "added", file: plan.file };
+  } catch (error) {
+    if (error instanceof Cancelled) return { status: "declined" };
+    terminal.warn("Installation is complete. The optional user feedback note could not be added; the guidance file needs review.");
+    return { status: "failed", reason: "guidance_file_needs_review" };
+  }
+}
+
+export {
+  planAgentNote,
+  applyAgentNote,
+  offerAgentNote
+};