feat(cli): prompt to select docs paths on ask add

[amondnet]

Summary

• User-facing change: ask add <spec> now detects candidate documentation paths from already-installed node_modules and the local ask cache, and shows an interactive multiselect prompt when more than one candidate exists. The selected paths are saved in ask.json as an object entry ({ "spec": "npm:next", "docsPaths": ["docs", "dist/docs"] }); plain string entries remain fully supported.
• New flags: --docs-paths <csv> skips the prompt and records the supplied paths directly; --clear-docs-paths downgrades an object entry back to a bare string, removing the override.
• Schema evolution: ask.json libraries entries now accept string | { spec, docsPaths[] }. The change is back-compatible — all existing string entries continue to parse unchanged. Helpers specFromEntry, docsPathsFromEntry, and entryFromSpec are exported from @pleaseai/schema and used throughout the CLI so there is a single source of truth for entry coercion.
• Offline-first design: ask add never triggers a fresh clone or network request. Candidate gathering reads only node_modules/<pkg>/ and whatever is already in the ask store (<askHome>/github/…). This keeps ask add fast and usable without network access.
• ask docs honors the override: When docsPaths is stored, ask docs <spec> resolves each path against both roots and emits only matched paths. If every stored path is stale it warns to stderr and falls back to the full unfiltered walk, so the command never silently returns nothing.

Test plan

• bun run build — clean across the workspace
• bun run --cwd packages/cli lint — clean
• bun run --cwd packages/schema lint — clean
• bun run --cwd packages/cli test — 497 pass, 0 fail (32 new tests: add.test.ts, candidates.test.ts, 4 new cases in docs.test.ts)
• bun run --cwd packages/schema test — 63 pass, 0 fail (9 new tests in ask-json.test.ts)

---

Summary by cubic

Adds an interactive docs-paths picker to ask add <spec> and makes ask docs honor saved paths. Also hardens path handling and preserves root selections.

• New Features

  • ask add <spec> scans node_modules/<pkg> and any cached checkout, shows a multiselect when multiple doc-like dirs exist, and saves chosen relative paths under docsPaths in ask.json.
  • Flags: --docs-paths <csv> to skip the prompt; --clear-docs-paths to remove the override.
  • ask docs <spec> resolves stored paths against both roots and emits only matches; warns and falls back to a full walk if all are stale.
  • Offline-first: never fetches or clones on add.
  • Schema: ask.json libraries accept string | { spec, docsPaths[] } (back-compatible). Helpers specFromEntry, docsPathsFromEntry, entryFromSpec exported from @pleaseai/schema; CLI adds findEntry for lookups.

• Bug Fixes

  • Guard against path traversal in stored docsPaths when resolving in ask docs; invalid entries are dropped and the stale-path fallback is used.
  • Sanitize --docs-paths values to reject absolute and parent-traversal paths; unsafe entries are ignored.
  • Preserve a root pick from the prompt by storing "." so it round-trips correctly.

^{Written for commit df95077. Summary will update on new commits.}

[codecov]

Codecov Report

❌ Patch coverage is 93.88489% with 17 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/cli/src/io.ts	63.15%	7 Missing ⚠️
packages/cli/src/commands/add.ts	96.62%	6 Missing ⚠️
packages/cli/src/interactive.ts	25.00%	3 Missing ⚠️
packages/cli/src/storage.ts	66.66%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[cloudflare-workers-and-pages]

Deploying ask-registry with    Cloudflare Pages

Latest commit:	df95077
Status:	✅  Deploy successful!
Preview URL:	https://e10fecac.ask-registry.pages.dev
Branch Preview URL:	https://amondnet-ask-add-docs-paths.ask-registry.pages.dev

View logs

[cubic-dev-ai]

3 issues found across 13 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/cli/src/commands/docs.ts">

<violation number="1" location="packages/cli/src/commands/docs.ts:90">
P1: `docsPaths` entries are not constrained to stay under the allowed roots, so `..`/absolute values can escape and emit arbitrary filesystem paths.</violation>
</file>

<file name="packages/cli/src/commands/add.ts">

<violation number="1" location="packages/cli/src/commands/add.ts:115">
P1: Validate `--docs-paths` entries to reject absolute paths and traversal segments before persisting.</violation>

<violation number="2" location="packages/cli/src/commands/add.ts:171">
P2: Root docs-path selections are silently discarded because empty relative paths are filtered out.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User
    participant CLI as CLI (add/docs)
    participant Discovery as Discovery Logic
    participant FS as Local FS (node_modules/cache)
    participant Prompt as consola.prompt
    participant Store as ask.json

    Note over User, Store: Flow: ask add <spec>

    User->>CLI: ask add <spec>
    CLI->>Discovery: NEW: gatherDocsCandidates(spec)
    
    Discovery->>FS: Check node_modules/<pkg>
    Discovery->>FS: Check <askHome>/github/... (offline only)
    FS-->>Discovery: Return found doc-like paths
    Discovery-->>CLI: Return candidate groups

    alt NEW: User provided --docs-paths <csv>
        CLI->>CLI: Parse CSV paths
    else NEW: Interactive TTY + Multiple candidates
        CLI->>Prompt: Show multiselect picker
        Prompt-->>CLI: User selected paths
    else No candidates or --clear-docs-paths
        CLI->>CLI: Fallback to bare spec string
    end

    CLI->>CLI: NEW: entryFromSpec(spec, paths)
    CLI->>Store: CHANGED: Save entry (string | {spec, docsPaths[]})
    Store-->>CLI: Success
    CLI-->>User: Entry added/updated

    Note over User, Store: Flow: ask docs <spec> (Consumer)

    User->>CLI: ask docs <spec>
    CLI->>Store: Read ask.json
    Store-->>CLI: Return entries
    
    CLI->>CLI: NEW: docsPathsFromEntry(entry)
    
    alt NEW: docsPaths override exists
        loop For each stored path
            CLI->>FS: Resolve relative path against roots
            opt Path exists on disk
                CLI-->>User: Emit absolute path
            end
        end
        opt NEW: All stored paths are stale
            CLI->>CLI: Warn and fall back to full directory walk
        end
    else No override
        CLI->>CLI: Execute default unfiltered walk
    end

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

0 issues found across 3 files (changes from recent commits).

_{Requires human review: Auto-approval blocked by 3 unresolved issues from previous reviews.}

[cubic-dev-ai]

1 issue found across 4 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/cli/src/commands/add.ts">

<violation number="1" location="packages/cli/src/commands/add.ts:36">
P2: Using `path.normalize` here stores OS-specific separators in `ask.json`, which breaks cross-platform portability of saved `docsPaths` (especially Windows `\\` paths used later on POSIX).</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}