@userreason/wizard 0.1.0 → 0.2.0

package/dist/chunk-3RDJORRS.js

@@ -0,0 +1,153 @@
+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 {
+  CredentialStoreError,
+  object,
+  string,
+  uuid
+} from "./chunk-GGARVSPT.js";
+
+// src/connection.ts
+import { createHash, randomBytes } from "node:crypto";
+var BrowserConnectionUnavailable = class extends Error {
+};
+function retryableNetworkError(error) {
+  if (!(error instanceof Error)) return false;
+  const cause = error.cause;
+  const rawCode = error.code ?? cause?.code;
+  const code = typeof rawCode === "string" ? rawCode : void 0;
+  if (code && !["ECONNRESET", "ETIMEDOUT", "EAI_AGAIN", "ECONNREFUSED", "ENETUNREACH"].includes(code)) return false;
+  return error.name === "TimeoutError" || error.name === "AbortError" || error instanceof TypeError && error.message === "fetch failed";
+}
+function memoryCredentials(session = null) {
+  let value = session;
+  return {
+    load: async () => value,
+    save: async (next) => {
+      value = next;
+    },
+    clear: async () => {
+      value = null;
+    }
+  };
+}
+async function compatibilityCredentials(existing, sessionOnly, confirm) {
+  if (sessionOnly) return { credentials: memoryCredentials(), session: null, sessionOnly: true };
+  try {
+    return { credentials: existing, session: await existing.load(), sessionOnly: false };
+  } catch (error) {
+    if (!(error instanceof CredentialStoreError) || error.code === "invalid_session" || !await confirm(error)) throw error;
+    return { credentials: memoryCredentials(), session: null, sessionOnly: true };
+  }
+}
+async function connectInstallation(config, input, onBrowser, options = {}) {
+  const fetcher = options.fetcher ?? fetch, now = options.now ?? Date.now;
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const discovery = await fetcher(`${config.apiUrl}/onboarding/v1/auth-config?installation=1`, {
+    redirect: "error",
+    signal: AbortSignal.timeout(1e4)
+  });
+  if (!discovery.ok) throw new Error(`Unable to discover installation login (${discovery.status})`);
+  const capabilities = object(await discovery.json(), "installation capabilities");
+  if (capabilities.client_id !== config.clientId)
+    throw new Error("Installation authentication client does not match the configured API");
+  options.onCapabilities?.({ unrestrictedOrigins: capabilities.unrestricted_origins === 1 });
+  if (capabilities.installation_login !== 1)
+    throw new BrowserConnectionUnavailable("This API uses device authentication");
+  const verifier = randomBytes(32).toString("hex"), challenge = createHash("sha256").update(verifier).digest("hex");
+  async function post(path, body, timeout = 2e4) {
+    return fetcher(`${config.apiUrl}/onboarding/v1/installations/${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      redirect: "error",
+      signal: AbortSignal.timeout(timeout)
+    });
+  }
+  const started = await post("start", {
+    challenge,
+    project_name: input.projectName,
+    workspace_id: input.workspaceId ?? null,
+    workspace_name: input.workspaceName ?? null,
+    site_id: input.siteId ?? null
+  });
+  if (started.status === 404)
+    throw new BrowserConnectionUnavailable("This API does not support browser installation yet");
+  if (!started.ok)
+    throw new Error(`Unable to start installation (${started.status}). Check the API deployment.`);
+  const data = object(await started.json(), "installation request"), id = uuid(string(data.id, "installation ID"));
+  const target = new URL(string(data.browser_url, "browser URL"));
+  const ticket = string(data.ticket, "installation ticket");
+  if (target.protocol !== "https:" && !(target.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(target.hostname)) || target.username || target.password || target.pathname !== "/install" || target.searchParams.get("id") !== id || new URLSearchParams(target.hash.slice(1)).get("request") !== ticket)
+    throw new Error("Invalid installation browser URL");
+  const expires = Date.parse(string(data.expires_at, "installation expiry"));
+  if (!Number.isFinite(expires) || expires <= now() || expires > now() + 901e3 || data.code !== challenge.slice(0, 8).toUpperCase())
+    throw new Error("Invalid installation request");
+  await onBrowser(target.href, String(data.code));
+  const waitingSince = now();
+  const deadline = Math.min(expires, waitingSince + 6e5);
+  let failures = 0, lastFailure;
+  const progress = (phase, httpStatus) => options.onProgress?.({
+    phase,
+    elapsedSeconds: Math.max(0, Math.floor((now() - waitingSince) / 1e3)),
+    consecutiveFailures: failures,
+    ...httpStatus === void 0 ? {} : { httpStatus }
+  });
+  progress("waiting");
+  while (now() < deadline) {
+    await sleep(Math.min(failures ? 5e3 : 3e3, deadline - now()));
+    if (now() >= deadline) break;
+    let response;
+    try {
+      response = await post("exchange", { id, ticket, verifier }, Math.max(1, Math.min(2e4, deadline - now())));
+    } catch (error) {
+      if (!retryableNetworkError(error)) throw error;
+      failures++;
+      lastFailure = "network connection";
+      progress("retrying");
+      continue;
+    }
+    if (response.status === 429 || response.status >= 500) {
+      failures++;
+      lastFailure = `HTTP ${response.status}`;
+      progress("retrying", response.status);
+      continue;
+    }
+    if (!response.ok)
+      throw new Error(
+        `Installation connection expired or failed (${response.status}). Run the wizard again.`
+      );
+    const result = object(await response.json(), "installation connection");
+    failures = 0;
+    lastFailure = void 0;
+    if (result.status === "pending") {
+      progress("waiting");
+      continue;
+    }
+    if (result.status !== "approved") throw new Error("Installation was declined.");
+    const user = object(result.user, "installation user"), expiry = Date.parse(string(result.expires_at, "access expiry"));
+    if (!Number.isFinite(expiry) || expiry > expires || expiry < now() + 6e4)
+      throw new Error("Installation access expired. Run the wizard again.");
+    return {
+      session: {
+        ...config,
+        accessToken: string(result.access_token, "installation token"),
+        refreshToken: "",
+        expiresAt: expiry,
+        userId: uuid(string(user.id, "user ID")),
+        email: string(user.email, "email")
+      },
+      workspaceId: result.workspace_id === null ? null : uuid(string(result.workspace_id, "workspace ID")),
+      workspaceName: result.workspace_name === null ? null : string(result.workspace_name, "workspace name"),
+      grantId: uuid(string(result.grant_id, "grant ID"))
+    };
+  }
+  if (failures) throw new Error(`Unable to confirm browser approval: the API is still failing (${lastFailure}). Run the wizard again when the connection is available.`);
+  throw new Error("Browser approval timed out. Finish sign-in and approval in the browser, then run the wizard again.");
+}
+
+export {
+  BrowserConnectionUnavailable,
+  memoryCredentials,
+  compatibilityCredentials,
+  connectInstallation
+};

package/dist/chunk-5Z5J6PY5.js

@@ -0,0 +1,258 @@
+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
+} from "./chunk-YMSGDC4B.js";
+import {
+  require_dist
+} from "./chunk-OEGNGGZ2.js";
+import {
+  __toESM
+} from "./chunk-WL3NOIM6.js";
+
+// src/agent-skill.ts
+var import_yaml = __toESM(require_dist(), 1);
+import { constants } from "node:fs";
+import { createHash } from "node:crypto";
+import { lstat, readFile, readdir, mkdir, open, unlink, rmdir } from "node:fs/promises";
+import { join, relative } from "node:path";
+var directories = [".agents", ".cursor", ".claude", ".codex"];
+var files = ["references/management.md", "SKILL.md"];
+var LEGACY_MANIFEST = ".userreason.json";
+var VERSION_KEY = "userreason-version";
+var FINGERPRINT_KEY = "userreason-content-sha256";
+var EARLIER = [
+  { "SKILL.md": "ac7d0e8a407e7bfb8fd734ba38aa548df52df3251ac1826208e142a2dc96b348", "references/management.md": "613981e7ad7eb1f92c2fda73396df532783b3622384c46c0ff608ae9ba79d8d1" }
+];
+var hash = (content) => createHash("sha256").update(content).digest("hex");
+var same = (a, b) => Object.keys(a).length === Object.keys(b).length && Object.entries(a).every(([path, value]) => b[path] === value);
+var fingerprint = (files2) => hash(JSON.stringify(Object.entries(files2).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)));
+function frontmatter(content) {
+  const match = /^(---\r?\n)([\s\S]*?\r?\n)---(?=\r?\n|$)/.exec(content);
+  if (!match) return null;
+  const document = (0, import_yaml.parseDocument)(match[2]);
+  if (document.errors.length || !(0, import_yaml.isMap)(document.contents)) return null;
+  return { document, start: match[1].length, end: match[1].length + match[2].length };
+}
+function trackedSkill(content) {
+  const parsed = frontmatter(content);
+  const metadata = parsed?.document.get("metadata", true);
+  if (!parsed || !(0, import_yaml.isMap)(metadata)) return null;
+  const version = metadata.get(VERSION_KEY, true), digest = metadata.get(FINGERPRINT_KEY, true);
+  if (!(0, import_yaml.isScalar)(version) || typeof version.value !== "string" || !(0, import_yaml.isScalar)(digest) || typeof digest.value !== "string" || !/^[a-f0-9]{64}$/.test(digest.value) || !digest.range) return null;
+  const [start, end] = digest.range;
+  return {
+    fingerprint: digest.value,
+    content: content.slice(0, parsed.start + start) + '""' + content.slice(parsed.start + end)
+  };
+}
+async function installed(path) {
+  const current = {}, snapshot = {}, normalized = {};
+  let recorded = null;
+  let expectedFingerprint = null;
+  for (const folder of ["", "references"]) {
+    let entries;
+    try {
+      entries = await readdir(join(path, folder), { withFileTypes: true });
+    } catch (error) {
+      if (folder && error.code === "ENOENT") continue;
+      throw error;
+    }
+    for (const entry of entries) {
+      if (!folder && entry.name === "references" && entry.isDirectory() && !entry.isSymbolicLink()) continue;
+      const name = folder ? `${folder}/${entry.name}` : entry.name, metadata = await lstat(join(path, name));
+      if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.nlink !== 1 || metadata.size > 1e6) return null;
+      const content = await readFile(join(path, name));
+      snapshot[name] = hash(content);
+      if (name !== LEGACY_MANIFEST) {
+        current[name] = snapshot[name];
+        const tracked = name === "SKILL.md" ? trackedSkill(content.toString("utf8")) : null;
+        normalized[name] = tracked ? hash(tracked.content) : current[name];
+        if (tracked) expectedFingerprint = tracked.fingerprint;
+        continue;
+      }
+      try {
+        const parsed = JSON.parse(content.toString("utf8"));
+        if (!parsed.files || typeof parsed.files !== "object" || Object.values(parsed.files).some((value) => typeof value !== "string")) return null;
+        recorded = parsed.files;
+      } catch {
+        return null;
+      }
+    }
+  }
+  return {
+    current,
+    recorded,
+    snapshot,
+    managed: expectedFingerprint !== null ? fingerprint(normalized) === expectedFingerprint : recorded !== null ? same(current, recorded) : EARLIER.some((earlier) => same(current, earlier))
+  };
+}
+async function safeDirectory(root, parts, create = false) {
+  let path = root;
+  for (const part of parts) {
+    path = join(path, part);
+    let metadata;
+    try {
+      metadata = await lstat(path);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      if (!create) return false;
+      try {
+        await mkdir(path);
+      } catch (error2) {
+        if (error2.code !== "EEXIST") throw error2;
+      }
+      metadata = await lstat(path);
+    }
+    if (!metadata.isDirectory() || metadata.isSymbolicLink()) throw new Error("The skill directory needs review.");
+  }
+  return true;
+}
+async function packaged(project) {
+  const assets = await Promise.all(files.map(async (path) => ({
+    path,
+    content: (await readFile(new URL(`./skills/userreason/${path}`, import.meta.url), "utf8")).replaceAll("npx --no-install userreason", cliCommand(project))
+  })));
+  const skill = assets.find((file) => file.path === "SKILL.md");
+  const parsed = frontmatter(skill.content);
+  if (!parsed) throw new Error("The packaged skill needs valid YAML frontmatter.");
+  const { version } = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+  if (typeof version !== "string") throw new Error("The wizard package needs a version.");
+  parsed.document.setIn(["metadata", VERSION_KEY], version);
+  parsed.document.setIn(["metadata", FINGERPRINT_KEY], "");
+  skill.content = skill.content.slice(0, parsed.start) + parsed.document.toString({ lineWidth: 0 }) + skill.content.slice(parsed.end);
+  const digest = fingerprint(Object.fromEntries(assets.map((file) => [file.path, hash(file.content)])));
+  const ready = frontmatter(skill.content);
+  const scalar = ready.document.getIn(["metadata", FINGERPRINT_KEY], true);
+  if (!(0, import_yaml.isScalar)(scalar) || !scalar.range) throw new Error("The packaged skill needs tracking metadata.");
+  skill.content = skill.content.slice(0, ready.start + scalar.range[0]) + JSON.stringify(digest) + skill.content.slice(ready.start + scalar.range[1]);
+  return assets;
+}
+async function updateAgentSkill(plan) {
+  const { folder, snapshot } = plan.update;
+  await safeDirectory(plan.directory, [folder, "skills", "userreason"]);
+  const now = await installed(plan.path);
+  if (!now || !same(now.snapshot, snapshot)) throw new Error("The skill changed after the preview.");
+  await safeDirectory(plan.directory, [folder, "skills", "userreason", "references"], true);
+  const write = async (name, content) => {
+    const handle = await open(join(plan.path, name), constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | (constants.O_NOFOLLOW ?? 0), 420);
+    try {
+      if (!(await handle.stat()).isFile()) throw new Error("The skill directory needs review.");
+      await handle.writeFile(content, "utf8");
+    } finally {
+      await handle.close();
+    }
+  };
+  for (const file of plan.files) await write(file.path, file.content);
+  for (const name of Object.keys(now.current)) if (!plan.files.some((file) => file.path === name)) await unlink(join(plan.path, name));
+  if (Object.hasOwn(now.snapshot, LEGACY_MANIFEST)) await unlink(join(plan.path, LEGACY_MANIFEST));
+}
+async function planAgentSkill(project) {
+  const host = { ...project, packageManager: project.packageManager ?? "npm" };
+  for (const folder of directories) {
+    if (!await safeDirectory(project.directory, [folder, "skills"])) continue;
+    const path = join(project.directory, folder, "skills", "userreason");
+    let metadata;
+    try {
+      metadata = await lstat(path);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      continue;
+    }
+    const preserved = {
+      status: metadata.isDirectory() && !metadata.isSymbolicLink() ? "already_present" : "skipped",
+      path: relative(project.directory, path),
+      reason: "existing_skill_preserved"
+    };
+    if (preserved.status !== "already_present") return preserved;
+    const found = await installed(path), assets2 = await packaged(host);
+    if (!found?.managed) return preserved;
+    if (!Object.hasOwn(found.snapshot, LEGACY_MANIFEST) && same(found.current, Object.fromEntries(assets2.map((file) => [file.path, hash(file.content)])))) return { ...preserved, reason: "up_to_date" };
+    return { directory: project.directory, path, files: assets2, update: { folder, snapshot: found.snapshot } };
+  }
+  const assets = await packaged(host);
+  return { directory: project.directory, path: join(project.directory, ".agents/skills/userreason"), files: assets };
+}
+async function applyAgentSkill(plan) {
+  if (plan.update) return updateAgentSkill(plan);
+  await safeDirectory(plan.directory, [".agents", "skills"], true);
+  await mkdir(plan.path);
+  const metadata = await lstat(plan.path);
+  const created = [];
+  try {
+    await safeDirectory(plan.directory, [".agents", "skills", "userreason", "references"], true);
+    for (const file of plan.files) {
+      await safeDirectory(plan.directory, [".agents", "skills", "userreason", ...file.path.split("/").slice(0, -1)]);
+      const current = await lstat(plan.path);
+      if (current.dev !== metadata.dev || current.ino !== metadata.ino) throw new Error("The skill directory changed after creation.");
+      const path = join(plan.path, file.path);
+      const handle = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 420);
+      try {
+        const info = await handle.stat();
+        created.push({ path, dev: info.dev, ino: info.ino });
+        await handle.writeFile(file.content, "utf8");
+      } finally {
+        await handle.close();
+      }
+    }
+  } catch (error) {
+    const current = await lstat(plan.path).catch(() => void 0);
+    if (current?.isDirectory() && !current.isSymbolicLink() && current.dev === metadata.dev && current.ino === metadata.ino) {
+      for (const file of created.reverse()) {
+        const info = await lstat(file.path).catch(() => void 0);
+        if (info?.isFile() && !info.isSymbolicLink() && info.dev === file.dev && info.ino === file.ino)
+          await unlink(file.path).catch(() => {
+          });
+      }
+      await rmdir(join(plan.path, "references")).catch(() => {
+      });
+      await rmdir(plan.path).catch(() => {
+      });
+    }
+    throw error;
+  }
+}
+async function offerAgentSkill(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 planAgentSkill(project);
+    if (!("files" in plan)) {
+      terminal.info(plan.reason === "up_to_date" ? `UserReason agent skill is up to date at ${plan.path}` : `Existing UserReason agent skill preserved at ${plan.path}`);
+      return plan;
+    }
+    if (plan.update) {
+      const where = relative(plan.directory, plan.path);
+      if (options.preview !== false) terminal.note(`The UserReason skill in ${where} is an earlier version that nobody edited.
+This replaces its files with the current version.`, "Optional skill update");
+      if (!options.requested && !await terminal.confirm("Update the UserReason feedback skill?", true, { recommended: true }))
+        return { status: "declined", path: where };
+      await applyAgentSkill(plan);
+      terminal.success(`Feedback skill updated in ${where}`);
+      return { status: "updated", path: where };
+    }
+    const entry = plan.files.find((file) => file.path === "SKILL.md").content;
+    const description = /^description: (.+)$/m.exec(entry)[1];
+    if (options.preview !== false) terminal.note(`${description}
+
+Adds .agents/skills/userreason/SKILL.md and references/management.md.
+Agents can propose feedback investigations, read the current documentation and use authenticated management when requested.`, "Optional project agent skill");
+    if (!options.requested && !await terminal.confirm("Install the UserReason feedback skill for your agents?", true, { recommended: true }))
+      return { status: "declined" };
+    await applyAgentSkill(plan);
+    terminal.success("Feedback skill installed in .agents/skills/userreason");
+    return { status: "added", path: ".agents/skills/userreason" };
+  } catch (error) {
+    if (error instanceof Cancelled) return { status: "declined" };
+    terminal.warn("Installation is complete. The optional agent skill could not be installed; the skill directory needs review.");
+    return { status: "failed", reason: "skill_directory_needs_review" };
+  }
+}
+
+export {
+  planAgentSkill,
+  applyAgentSkill,
+  offerAgentSkill
+};

package/dist/chunk-6CJ4ANMN.js

@@ -0,0 +1,70 @@
+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 {
+  currentPackageProfile
+} from "./chunk-GGARVSPT.js";
+
+// src/startup.ts
+import { readFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { constants } from "node:os";
+var HANDOFF = "USERREASON_WIZARD_HANDOFF";
+async function wizardVersion() {
+  const { version } = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+  if (typeof version !== "string") throw new Error("The wizard package needs a version.");
+  return version;
+}
+async function ensureCurrentWizard(embedded, version, options = {}) {
+  const profile = await currentPackageProfile(embedded, options.fetcher);
+  if (profile.kind !== "local-development") return { profile };
+  if (version === profile.wizardVersion && embedded.wizardVersion === version && embedded.buildId === profile.buildId && embedded.sdkVersion === profile.sdkVersion && embedded.cliVersion === profile.cliVersion)
+    return { profile };
+  const env = options.env ?? process.env;
+  if (env[HANDOFF]) throw new Error("The relaunched wizard is not the current local build. No setup was performed. Check dev:packages and rerun the command.");
+  const args = options.args ?? process.argv.slice(2);
+  const nodeOptions = [env.NODE_OPTIONS, ...(options.execArgv ?? process.execArgv).map((arg) => JSON.stringify(arg))].filter(Boolean).join(" ");
+  const npmArgs = [
+    "-y",
+    "--prefer-online",
+    `--registry=${profile.registry}`,
+    `--@userreason:registry=${profile.registry}`,
+    ...nodeOptions ? [`--node-options=${nodeOptions}`] : [],
+    `@userreason/wizard@${profile.wizardVersion}`,
+    ...args
+  ];
+  const socket = Boolean(env.SOCKET_CLI_API_BASE_URL);
+  options.onRestart?.(`Wizard ${version} is out of date. Starting local wizard ${profile.wizardVersion}\u2026`);
+  const exitCode = await new Promise((resolve, reject) => {
+    const child = spawn(socket ? "socket" : "npx", socket ? ["npx", ...npmArgs] : npmArgs, {
+      cwd: process.cwd(),
+      shell: false,
+      stdio: "inherit",
+      env: { ...env, [HANDOFF]: "1", ...nodeOptions ? { NODE_OPTIONS: nodeOptions } : {} }
+    });
+    const interrupt = () => {
+      child.kill("SIGINT");
+    };
+    const terminate = () => {
+      child.kill("SIGTERM");
+    };
+    const cleanup = () => {
+      process.off("SIGINT", interrupt);
+      process.off("SIGTERM", terminate);
+    };
+    process.on("SIGINT", interrupt);
+    process.on("SIGTERM", terminate);
+    child.once("error", () => {
+      cleanup();
+      reject(new Error("Unable to start the current local wizard. No setup was performed. Check your package launcher and its permissions."));
+    });
+    child.once("close", (code, signal) => {
+      cleanup();
+      resolve(code ?? (signal ? 128 + constants.signals[signal] : 1));
+    });
+  });
+  return { profile, exitCode };
+}
+
+export {
+  wizardVersion,
+  ensureCurrentWizard
+};