@fadhelhaidar/pi-ask-user 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 juicesharp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,43 @@
+# Attribution and provenance
+
+## Original project
+
+This extension is derived from [juicesharp/rpiv-mono](https://github.com/juicesharp/rpiv-mono),
+specifically [`packages/rpiv-ask-user-question`](https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-ask-user-question),
+published as `@juicesharp/rpiv-ask-user-question`. The original code is MIT-licensed
+and authored by juicesharp. This is an extraction of that implementation with
+personal patches, not an independently written replacement.
+
+## Source lineage
+
+1. Local interaction patches began against the published 2.12.0 extension.
+2. The patches were ported into the personal fork `FadhelHaidar/rpiv-mono`,
+   based on upstream commit
+   [`68d9a0014b70006d7b04b57933752338a2716db7`](https://github.com/juicesharp/rpiv-mono/commit/68d9a0014b70006d7b04b57933752338a2716db7).
+3. The patched extension was extracted into `FadhelHaidar/pi-ask-user` from
+   fork snapshot `c814ebb34cbcf68143ea88089be8c7cd1a69159c`.
+
+Patch identifiers in the former fork (recorded here for provenance, not as
+required downloads or links to a repository that must remain online):
+
+- `76abd683b1a300e4962ed1ec2288c6430c10fadb` — combined multi-select/custom
+  answers, Enter-only toggling, immediate custom-row editing, and draft retention.
+- `023c6ac46e7eb99e7a3e3558ef13aba8bcff7090` — regression coverage for those behaviors.
+
+## Customization and independent maintenance
+
+The interaction changes let custom text supplement predefined selections while
+keeping checkbox selection distinct from typing and preserving unchecked drafts.
+The standalone extraction removes the need to maintain or install a full
+monorepo fork for this single tool. This project owns its releases; upstream
+synchronization and upstream PR preparation are not part of its maintenance workflow.
+
+`lib/config-io.ts` and the fixtures in `test/utils/` were also extracted from
+that MIT-licensed source tree. Original copyright is retained in LICENSE.
+
+This repository is maintained independently. It does not require the monorepo,
+an upstream checkout, or the rpiv-config npm package. The rpiv-i18n integration
+remains optional at runtime; its published package is used for localization tests.
+
+The tool name, rpiv event names, localization namespace, and configuration path
+remain unchanged for compatibility with existing sessions and other extensions.

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# pi-ask-user
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A standalone Pi extension providing the `ask_user_question` tool: tabbed questionnaires, single- and multi-select choices, custom answers, notes, and markdown previews.
+
+Maintained independently by FadhelHaidar. No monorepo checkout or upstream-sync workflow is needed.
+
+## Origin and why this version exists
+
+This project is derived from **juicesharp's [`@juicesharp/rpiv-ask-user-question`](https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-ask-user-question)**, originally part of the MIT-licensed [`juicesharp/rpiv-mono`](https://github.com/juicesharp/rpiv-mono) monorepo. The original author built the questionnaire UI and tool; this repository preserves that work and its copyright notice.
+
+The customization started as local patches to the published **2.12.0** extension, then moved into a personal monorepo fork, `FadhelHaidar/rpiv-mono`. This standalone repository extracts that patched extension rather than rewriting it. Its upstream baseline is commit [`68d9a0014b70006d7b04b57933752338a2716db7`](https://github.com/juicesharp/rpiv-mono/commit/68d9a0014b70006d7b04b57933752338a2716db7); the extraction snapshot and patch identifiers are recorded in [NOTICE.md](NOTICE.md), even if the former personal fork is deleted.
+
+### Why customize the interaction?
+
+The goal is to make multi-select questions work naturally when the available choices are useful **but not exhaustive**:
+
+- **Choose options and add your own answer together.** Custom text should supplement checked choices, not replace them. For example, selecting “Unit tests” and “Integration tests” can also include “Add a smoke test on deployment.”
+- **Keep typing separate from checkbox toggling.** Enter explicitly toggles a checkbox; Space is text in the custom editor and never toggles a checkbox.
+- **Type as soon as the custom row is focused.** There is no extra step to open the editor, and Enter toggles whether the text is included without closing the editor.
+- **Do not lose work when changing your mind.** Unchecking custom text excludes it from the submitted answer but preserves the draft. Navigation and tab changes keep the draft available, and rechecking restores it.
+
+These are deliberate preferences for this version, not a claim that the original extension is unsuitable for everyone. Single-select behavior is preserved, and the multi-select changes have dedicated regression tests.
+
+### Why a standalone repository?
+
+Only the ask-user extension is needed here. Keeping an entire monorepo fork solely to install one customized tool adds unrelated packages, root-level packaging changes, and an upstream-sync workflow that this project does not need.
+
+This repository therefore owns its releases independently. The config helper and test fixtures needed by the extension are included locally, while Pi supplies the host APIs. Optional rpiv-i18n compatibility remains available. There is **no dependency on the former fork**, no requirement to track upstream releases, and no upstream PR workflow to maintain.
+
+## Install
+
+```sh
+pi install git:github.com/FadhelHaidar/pi-ask-user@v1.0.1
+```
+
+Starting with v1.0.1, Git releases include prebuilt JavaScript and translations in `dist/`. Installation uses these files directly: no Bun, compiler, development dependencies, or local build is required. Pi and its runtime dependencies are still required.
+
+Restart Pi after installing. Remove any other package registering `ask_user_question` to avoid duplicate registration.
+
+### GitSync and new machines
+
+Sync the Pi package declaration `git:github.com/FadhelHaidar/pi-ask-user@v1.0.1`, then install the declared package on the destination machine using Pi. If you sync a local checkout instead, include the tracked `dist/` directory and install it with `pi install /path/to/pi-ask-user`. Neither route needs `bun run build` on the destination.
+
+Pinned tags do not automatically advance. A machine still configured for `@v1.0.0` keeps the old package until you change the declaration to a prebuilt release tag. A tag must be published before the corresponding install command works; source changes alone do not create a release.
+
+Each new GitHub release also provides an npm-format `.tgz` containing the same prebuilt runtime. This does not publish the package to npm; the supported Pi installation route remains Git.
+
+## Preserved custom behavior
+
+- Multi-select answers can include predefined choices **and** custom text together.
+- **Enter** toggles checkboxes; Space remains ordinary text while typing.
+- The `Type something.` row is immediately editable when focused.
+- Unchecking the custom answer keeps its draft; rechecking restores it.
+- Drafts and checkbox state survive tab changes.
+- Single-select behavior remains unchanged.
+
+Use arrow keys to move, Tab to switch questions, Enter to choose/toggle, and Esc to cancel. The custom-answer row is appended automatically; models must not author it. Previews are available for single-select questions. Ctrl+] collapses the overlay, Shift+Enter adds a line, and Ctrl+G opens the external editor.
+
+## Compatibility and configuration
+
+The tool remains named `ask_user_question`. Event names and the localization namespace are preserved for compatibility. Existing configuration remains at `~/.config/rpiv-ask-user-question/config.json`, honoring `XDG_CONFIG_HOME` with legacy fallback.
+
+```json
+{ "collapseKey": "alt+o" }
+```
+
+The optional `@juicesharp/rpiv-i18n` integration is retained. Without it, the UI uses English. Runtime config helpers are included locally; no rpiv-config dependency is required.
+
+## Reference
+
+- [Tool schema](docs/tool-schema.md)
+- [Keyboard and layout](docs/keyboard.md)
+- [Configuration](docs/configuration.md)
+- [Hosts and runtime behavior](docs/hosts.md)
+- [Localization](docs/localization.md)
+
+## Development
+
+Requires Node.js 22+ and Bun.
+
+GitHub Actions is the routine builder. Branch pushes and pull requests build before checking freshness, types, and tests, so missing or stale committed `dist/` does not block source changes. After a successful run for `main`, a separate job commits only the tested `dist/` when it changed. It skips an outdated run if `main` has advanced and never force-pushes. Bot commits made with the repository's GitHub token do not trigger another workflow run.
+
+Local validation is optional:
+
+```sh
+bun install
+bun run build
+bun run build:check
+bun run typecheck
+bun run test
+pi -e ./index.ts
+```
+
+`pi -e ./index.ts` loads source for development. Use `pi -e ./dist/index.js` to smoke-test the shipped extension after building. For local builds, use Bun 1.4.2, matching CI: compiler versions can change artifact bytes. You can push source changes without routinely building or committing `dist/` locally; Actions updates the tracked runtime on `main`. Branch checkouts may have stale artifacts until built, and installations should use a completed prebuilt release. There are no install-time build hooks. TypeScript declarations ship with both public entry points. Event declarations are generated from `events.ts`; keep `scripts/index.d.ts.template` synchronized if the root factory signature or exports change.
+
+The workflow files must first be pushed to GitHub before Actions can run them. Repository or branch-protection rules may need to permit `github-actions[bot]` commits to `main` using the repository token. This project does not change those settings automatically. If publication is blocked or loses a concurrent push race, inspect the run and rerun the workflow for the latest `main` commit.
+
+Tests and fixtures live in this repository, including the multi-select/custom-answer regressions. Published optional localization is installed only for development tests. Pi supplies its host libraries at runtime; the build leaves bare package imports external.
+
+### Preparing a release
+
+1. Set `package.json` to the new release version and commit the source and manifest changes. Local build/test and `npm pack --dry-run --ignore-scripts` checks are optional validation.
+2. After review, push or merge the changes to `main` and wait for its Tests workflow, including `publish-dist`, to succeed. If `dist/` changed, wait for the automatic build commit to appear on `main`; if it did not change, no extra commit is needed.
+3. Fetch the updated `main` and inspect the commit you will tag. Only then create and push a matching `v<version>` tag (for this change, `v1.0.1`) on that fresh, prebuilt commit. Do not tag the earlier source-only commit or move an existing release tag.
+
+Tag pushes do not run the branch build/publish workflow. They validate the checked-in prebuilt runtime rather than silently rebuilding a release.
+
+The release workflow rejects tags that do not match `package.json`, checks build freshness, runs tests, packs the prebuilt files, and attaches both a versioned tarball and the stable `pi-ask-user.tgz` asset to each GitHub release. The stable URL `/releases/latest/download/pi-ask-user.tgz` lets Pi update to the newest published release without changing the package declaration. It uses the repository's GitHub token, not npm credentials. A GitHub Actions release run is required to produce the downloadable assets.
+
+## License
+
+MIT. Derived from juicesharp's rpiv-ask-user-question; original copyright is retained. See [LICENSE](LICENSE) and [NOTICE.md](NOTICE.md).

package/dist/chunks/external-editor-5wd19nyg.js

@@ -0,0 +1,51 @@
+// state/external-editor.ts
+import { spawn } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+function runEditor(command, file) {
+  const [editor, ...args] = command.split(" ");
+  if (!editor)
+    return Promise.reject(new Error("External editor command is empty"));
+  return new Promise((resolve, reject) => {
+    const child = spawn(editor, [...args, file], {
+      stdio: "inherit",
+      shell: process.platform === "win32"
+    });
+    child.once("error", reject);
+    child.once("close", (code, signal) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      const reason = signal ? `signal ${signal}` : `exit code ${code ?? "unknown"}`;
+      reject(new Error(`External editor exited with ${reason}`));
+    });
+  });
+}
+async function editWithExternalEditor(tui, command, value) {
+  const tempDir = mkdtempSync(join(tmpdir(), "rpiv-ask-user-question-"));
+  const tempFile = join(tempDir, "answer.md");
+  let tuiStopped = false;
+  try {
+    writeFileSync(tempFile, value, "utf8");
+    tui.stop();
+    tuiStopped = true;
+    process.stdout.write(`Launching external editor: ${command}
+Pi will resume when the editor exits.
+`);
+    await runEditor(command, tempFile);
+    return readFileSync(tempFile, "utf8").replace(/\r?\n$/, "");
+  } finally {
+    try {
+      rmSync(tempDir, { recursive: true, force: true });
+    } catch {}
+    if (tuiStopped) {
+      tui.start();
+      tui.requestRender(true);
+    }
+  }
+}
+export {
+  editWithExternalEditor
+};

package/dist/chunks/index-bx2tbz93.js

@@ -0,0 +1,5 @@
+// events.ts
+var ASK_USER_PROMPT_EVENT2 = "rpiv:ask-user:prompt";
+var ASK_USER_BLOCKED_EVENT2 = "rpiv:ask-user:blocked";
+
+export { ASK_USER_PROMPT_EVENT2, ASK_USER_BLOCKED_EVENT2 };

package/dist/chunks/index-x7fb685n.js

@@ -0,0 +1,226 @@
+// lib/config-io.ts
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+function expandTilde(p) {
+  if (p === "~")
+    return homedir();
+  if (p.startsWith("~/"))
+    return join(homedir(), p.slice(2));
+  return p;
+}
+function defaultConfigDir() {
+  return join(homedir(), ".config");
+}
+function resolveConfigDir() {
+  const xdg = readEnvVar("XDG_CONFIG_HOME");
+  if (!xdg)
+    return defaultConfigDir();
+  const expanded = expandTilde(xdg);
+  return isAbsolute(expanded) ? expanded : defaultConfigDir();
+}
+function legacyConfigPath(name, file = "config.json") {
+  return join(defaultConfigDir(), name, file);
+}
+function configPath(name, file = "config.json") {
+  return join(resolveConfigDir(), name, file);
+}
+function loadJsonConfig(path) {
+  if (!existsSync(path))
+    return {};
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+      return {};
+    return parsed;
+  } catch (err) {
+    console.warn(`rpiv-config: invalid JSON at ${path}, using default ({}) — ${err.message}`);
+    return {};
+  }
+}
+function loadJsonConfigWithLegacyFallback(name, file = "config.json") {
+  const xdgPath = configPath(name, file);
+  if (existsSync(xdgPath)) {
+    return loadJsonConfig(xdgPath);
+  }
+  return loadJsonConfig(legacyConfigPath(name, file));
+}
+var GuidanceFieldsSchema = Type.Object({
+  promptSnippet: Type.Optional(Type.String()),
+  promptGuidelines: Type.Optional(Type.Array(Type.String())),
+  description: Type.Optional(Type.String())
+}, { additionalProperties: true });
+function validateGuidanceFields(fields) {
+  if (!fields || typeof fields !== "object")
+    return {};
+  const g = fields;
+  const result = {};
+  if (typeof g.promptSnippet === "string" && g.promptSnippet.length > 0) {
+    result.promptSnippet = g.promptSnippet;
+  }
+  if (Array.isArray(g.promptGuidelines) && g.promptGuidelines.length > 0 && g.promptGuidelines.every((s) => typeof s === "string" && s.length > 0)) {
+    result.promptGuidelines = g.promptGuidelines;
+  }
+  if (typeof g.description === "string" && g.description.length > 0) {
+    result.description = g.description;
+  }
+  return result;
+}
+function readEnvVar(key, fallback) {
+  return process.env[key]?.trim() || fallback;
+}
+
+// config.ts
+var DEFAULT_COLLAPSE_KEY = "ctrl+]";
+var COLLAPSE_KEY_OFF = "off";
+var SPECIAL_KEYS = new Set([
+  "escape",
+  "esc",
+  "enter",
+  "return",
+  "tab",
+  "space",
+  "backspace",
+  "delete",
+  "insert",
+  "clear",
+  "home",
+  "end",
+  "pageup",
+  "pagedown",
+  "up",
+  "down",
+  "left",
+  "right",
+  ...Array.from({ length: 12 }, (_, i) => `f${i + 1}`)
+]);
+var MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
+function isValidCollapseKeySpec(spec) {
+  if (!spec)
+    return false;
+  if (spec.startsWith("+") || spec.endsWith("+") || spec.includes("++"))
+    return false;
+  const parts = spec.split("+");
+  const base = parts[parts.length - 1] ?? "";
+  const modifiers = parts.slice(0, -1);
+  if (modifiers.length !== new Set(modifiers).size)
+    return false;
+  if (!modifiers.every((m) => MODIFIERS.has(m)))
+    return false;
+  return base.length === 1 ? /[a-z0-9_\-!@#$%^&*()|~`'":;,./<>?[\]{}=\\]/.test(base) : SPECIAL_KEYS.has(base);
+}
+function resolveCollapseKey(config) {
+  const raw = config.collapseKey?.trim().toLowerCase();
+  if (raw === undefined || raw === "")
+    return DEFAULT_COLLAPSE_KEY;
+  if (raw === COLLAPSE_KEY_OFF)
+    return COLLAPSE_KEY_OFF;
+  return isValidCollapseKeySpec(raw) ? raw : DEFAULT_COLLAPSE_KEY;
+}
+var COMPOUND_KEY_DISPLAY = {
+  pageup: "PageUp",
+  pagedown: "PageDown"
+};
+function formatKeySpecForDisplay(spec) {
+  return spec.split("+").map((part) => COMPOUND_KEY_DISPLAY[part] ?? (part.length <= 1 ? part.toUpperCase() : part.charAt(0).toUpperCase() + part.slice(1))).join("+");
+}
+function loadConfig() {
+  return loadJsonConfigWithLegacyFallback("rpiv-ask-user-question");
+}
+
+// state/row-intent.ts
+var SENTINEL_KINDS = ["other", "next"];
+var ROW_INTENT_META = {
+  option: {
+    label: "",
+    reserved: false,
+    livesInMainList: true,
+    numbered: true,
+    activatesInputMode: false,
+    blocksMultiToggle: false,
+    autoSubmitsInMulti: false,
+    autoAppendOnSingleSelect: false,
+    autoAppendOnMultiSelect: false
+  },
+  other: {
+    label: "Type something.",
+    reserved: true,
+    livesInMainList: true,
+    numbered: true,
+    activatesInputMode: true,
+    blocksMultiToggle: false,
+    autoSubmitsInMulti: false,
+    autoAppendOnSingleSelect: true,
+    autoAppendOnMultiSelect: true
+  },
+  next: {
+    label: "Next",
+    reserved: true,
+    livesInMainList: true,
+    numbered: false,
+    activatesInputMode: false,
+    blocksMultiToggle: true,
+    autoSubmitsInMulti: true,
+    autoAppendOnSingleSelect: false,
+    autoAppendOnMultiSelect: true
+  }
+};
+var LABELS_BY_KIND = {
+  other: ROW_INTENT_META.other.label,
+  next: ROW_INTENT_META.next.label
+};
+var RESERVED_LABEL_SET = new Set([
+  "Other",
+  ...SENTINEL_KINDS.filter((k) => ROW_INTENT_META[k].reserved).map((k) => ROW_INTENT_META[k].label)
+]);
+function sentinelsToAppend(question) {
+  const out = [];
+  for (const k of SENTINEL_KINDS) {
+    const meta = ROW_INTENT_META[k];
+    if (!meta.livesInMainList)
+      continue;
+    if (question.multiSelect === true) {
+      if (meta.autoAppendOnMultiSelect)
+        out.push(k);
+    } else {
+      if (meta.autoAppendOnSingleSelect)
+        out.push(k);
+    }
+  }
+  return out;
+}
+
+// state/i18n-bridge.ts
+var I18N_NAMESPACE = "@juicesharp/rpiv-ask-user-question";
+var scopeImpl;
+try {
+  const sdk = await import("@juicesharp/rpiv-i18n");
+  scopeImpl = sdk.scope(I18N_NAMESPACE);
+} catch {
+  scopeImpl = (_key, fallback) => fallback;
+}
+var t = scopeImpl;
+function displayLabel(kind) {
+  return t(`sentinel.${kind}`, ROW_INTENT_META[kind].label);
+}
+
+// tool/format-answer.ts
+var NO_INPUT_PLACEHOLDER = "(no input)";
+function formatAnswerScalar(a, _variant) {
+  switch (a.kind) {
+    case "multi": {
+      const parts = [...a.selected ?? []];
+      if (a.answer && a.answer.length > 0)
+        parts.push(a.answer);
+      return parts.length > 0 ? parts.join(", ") : NO_INPUT_PLACEHOLDER;
+    }
+    case "custom":
+      return a.answer && a.answer.length > 0 ? a.answer : NO_INPUT_PLACEHOLDER;
+    case "option":
+      return a.answer ?? NO_INPUT_PLACEHOLDER;
+  }
+}
+
+export { validateGuidanceFields, DEFAULT_COLLAPSE_KEY, COLLAPSE_KEY_OFF, resolveCollapseKey, formatKeySpecForDisplay, loadConfig, ROW_INTENT_META, sentinelsToAppend, I18N_NAMESPACE, t, displayLabel, formatAnswerScalar };