feat(cli): PM-driven install flow with ask.json

[amondnet]

Closes #51

Summary

Replaces .ask/config.json + .ask/ask.lock + the ask docs *
namespace with a PM-driven install flow rooted in a top-level
ask.json. The project's package manager lockfile is now the single
source of truth for dependency versions, and ASK is repositioned as a
downstream tool of the user's PM (the same relationship Prisma /
TypeScript have to npm).

ask add npm:next                              # PM-driven entry
ask add github:vercel/next.js --ref v14.2.3   # Standalone github entry
ask install                                   # (Re)materialize everything

Architecture

• Schema — packages/schema/src/{ask-json,resolved}.ts. Two new
  entry shapes (PM-driven {spec} and standalone {spec, ref, docsPath?})
  validated via Zod. Drops the legacy Config/Lock schemas entirely.
• Lockfile readers — packages/cli/src/lockfiles/. The legacy
  manifest/ module is renamed and decomposed into per-format readers
  (bun, npm, pnpm, yarn, package-json) under a single
  npmEcosystemReader facade that probes them in priority order.
• Install orchestrator — packages/cli/src/install.ts:runInstall.
  Reads ask.json, resolves each entry against the right source of
  truth, short-circuits via .ask/resolved.json, dispatches to the
  existing source adapters unchanged, and writes .ask/docs/,
  AGENTS.md, and .claude/skills/<name>-docs/. Per-entry failures
  emit warnings and exit code is always 0 (postinstall-friendly).
• Flat command surface — ask install | add | remove | list. The
  docs namespace is gone — there is no deprecated wrapper.
• Spec helper — packages/cli/src/spec.ts. Single source of
  truth for translating an ask.json spec into a library slug.

Existing source adapters (sources/{npm,github,web,llms-txt}.ts) and
the registry resolver are intentionally untouched.

Behavioral changes

• ask install bootstraps an empty ask.json when missing (FR-8).
• Resolved-cache short-circuit on .ask/resolved.json (NFR-1, AC-9).
• Intent-skills format detected at first-pass via the existing
  local-intent adapter; the AGENTS.md marker block writer is reused.
• ignore-files now manages .ask/resolved.json alongside
  .ask/docs/.
• FR-5 deviation: github specs require an explicit --ref. The
  spec originally said "default to main with a warning"; during
  implementation we rejected the silent default because users could
  not reliably tell which version they were pinned to. Spec amended.

Test plan

• bun run --cwd packages/schema test — 47 pass
• bun run --cwd packages/cli build && lint && test — 219 pass, lint clean
• bun run --cwd apps/registry build — clean
• AC-10 sweep: zero actionable references to ask docs add /
  .ask/config.json / .ask/ask.lock in source, tests, fixtures,
  README, CLAUDE.md, skills, registry UI, or eval docs. Only
  historical-context lines (CLAUDE.md gotchas) retain the legacy
  names to document the rename.
• Manual smoke: in a fresh dir with bun init + bun add next,
  run ask add npm:next && ask install. Verify
  .ask/docs/next@<ver>/, AGENTS.md block,
  .claude/skills/next-docs/SKILL.md are produced and version
  matches bun.lock.
• Manual smoke: in a non-JS dir, declare a github: entry and
  run ask install. Verify .ask/docs/<name>@<ref>/ is populated.
• Manual smoke: re-run ask install twice in a row and confirm
  the second run reports "already up to date" with no source
  fetches (NFR-1, AC-9).

Track: pm-driven-install-20260410

---

Summary by cubic

Adds a PM-driven install flow with a root ask.json and ask install, making your package manager lockfile the single source of truth for versions. Removes ask docs * and the legacy .ask/config.json/.ask/ask.lock, and short-circuits repeat installs via .ask/resolved.json. Implements #51.

• New Features

  • ask.json entries: npm:<pkg> and github:<owner>/<repo> (requires --ref).
  • ask install reads bun.lock/package-lock.json/pnpm-lock.yaml/yarn.lock/package.json, writes .ask/docs/, AGENTS.md, skills, and caches to .ask/resolved.json; bootstraps empty ask.json; per-entry failures warn with exit code 0.
  • Lockfile readers split per format under npmEcosystemReader; CLI surface is flat: ask install | add | remove | list (no ask docs *).
  • Bug fix: normalize a leading v in GitHub --ref so cache keys and .ask/docs/<name>@<ver>/ match, preventing unnecessary re-fetches.

• Migration

  • Use ask add npm:<pkg> or ask add github:<owner>/<repo> --ref <tag>, then run ask install (works well in postinstall).
  • Keep the dependency in your PM; versions come from the lockfile. .ask/docs/ and .ask/resolved.json are managed by ASK and added to ignore files automatically.

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

[cloudflare-workers-and-pages]

Deploying ask-registry with    Cloudflare Pages

Latest commit:	b6e2395
Status:	🚫  Build failed.

View logs

[codecov]

Codecov Report

❌ Patch coverage is 69.25859% with 170 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/cli/src/install.ts	50.57%	128 Missing ⚠️
packages/cli/src/storage.ts	58.97%	16 Missing ⚠️
packages/cli/src/io.ts	73.46%	13 Missing ⚠️
packages/cli/src/lockfiles/index.ts	82.85%	6 Missing ⚠️
packages/cli/src/spec.ts	87.50%	4 Missing ⚠️
packages/cli/src/lockfiles/npm.ts	92.85%	2 Missing ⚠️
packages/cli/src/lockfiles/package-json.ts	96.15%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[cubic-dev-ai]

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

_{Requires human review: This is a major architectural refactor and feature change that replaces the core config and installation logic. The impact and risk are too high for auto-approval.}

[cubic-dev-ai]

1 issue found across 64 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/install.ts">

<violation number="1" location="packages/cli/src/install.ts:121">
P2: Normalize standalone GitHub refs to match the GitHub source’s resolvedVersion (strips a leading `v` for tags). Otherwise the resolved-cache check and docs path never match for tags like `v1.2.3`, forcing a re-fetch every install.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User as "CLI / User"
    participant Orchestrator as "Install Orchestrator (install.ts)"
    participant Lockfiles as "NPM Ecosystem Reader"
    participant Cache as "Resolved Cache (.ask/resolved.json)"
    participant Source as "Source Adapters (npm, github, web)"
    participant FS as "File System (.ask/docs, AGENTS.md)"

    User->>Orchestrator: NEW: ask install | add

    alt NEW: ask.json missing
        Orchestrator->>FS: NEW: Bootstrap empty ask.json
    end

    Orchestrator->>FS: NEW: Read ask.json (Libraries list)

    loop for each library entry
        alt NEW: PM-driven (e.g., npm:next)
            Orchestrator->>Lockfiles: CHANGED: Resolve version from lockfile
            Note over Lockfiles: Priority: bun.lock -> package-lock.json ->\npnpm-lock.yaml -> yarn.lock -> package.json
            Lockfiles-->>Orchestrator: Resolved version
        else NEW: Standalone (e.g., github:owner/repo)
            Note over Orchestrator: Use explicit --ref from ask.json
        end

        Orchestrator->>Cache: NEW: Check .ask/resolved.json
        alt NEW: Cache Hit (Same spec + version + files exist)
            Cache-->>Orchestrator: Skip fetch
        else NEW: Cache Miss / Force

            opt NEW: npm: entry
                Orchestrator->>Source: CHANGED: Check local node_modules
                Source-->>Orchestrator: Return local docs if version matches
            end

            alt Local Miss
                Orchestrator->>Source: Fetch documentation
                Source->>Source: Registry lookup / Network download
                Source-->>Orchestrator: Doc files + Content Hash
            end

            Orchestrator->>FS: CHANGED: Materialize .ask/docs/<name>@<ver>/
            Orchestrator->>FS: NEW: Generate Claude Skill (.claude/skills/)
            Orchestrator->>Cache: NEW: Update resolved entry + fetchedAt
        end
    end

    Orchestrator->>FS: CHANGED: Update AGENTS.md (Marker block)
    Orchestrator->>FS: CHANGED: manageIgnoreFiles (.gitignore, .prettierignore)

    Orchestrator-->>User: Exit 0 (Warnings for skipped/failed entries)

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 1 file (changes from recent commits).

_{Requires human review: Major architectural refactor (5k+ lines) that replaces the core configuration system and CLI command structure. High impact and risk require human verification of the new logic.}