feat(cli): add manifest gate and reject bare-name specs#25
Merged
Conversation
Introduces a stateless manifest reader module that inspects a project's lockfiles and manifests to find the installed version of a dependency. Lookup order: bun.lock > package-lock.json > pnpm-lock.yaml > yarn.lock > package.json (range). Lockfile hits return exact versions; package.json falls back to a range string with `exact: false` so callers can delegate to NpmResolver for semver normalization. The reader is pure and filesystem-driven, making it trivial to unit test with programmatic tmpdir fixtures (no committed fixture files). Refs #23
…mand Add Gate A (reject bare-name specs like `ask docs add next`) and Gate B (auto-resolve version from project lockfile/manifest when omitted) to the `add` command. Both gates are extracted as testable helpers (checkBareNameGate, runManifestGate) so the policy can be unit-tested without spinning up the full command. New flags: --no-manifest Skip lockfile/manifest lookup (preserve old 'latest' behavior) --from-manifest Require manifest hit; error if package not found locally Bare-name rejection error message guides users to either an ecosystem prefix (`npm:next`) or the GitHub shorthand (`vercel/next.js`). The parser (parseDocSpec) is intentionally NOT changed — it still returns `kind: 'name'` so other callers and the regression test in registry.test.ts continue to work; the rejection is a command-layer policy. Refs #23
…reference
The add-docs SKILL.md previously inlined a 332-line pipeline that mirrored
packages/cli/src/ logic, creating constant drift risk between the two
implementations. Restructure the skill so:
- SKILL.md (137 lines) holds only the happy path: parse user intent,
detect ecosystem, build a CLI spec, run `bunx @pleaseai/ask docs add`,
then verify the outputs. CLI is the single source of truth.
- references/inline-pipeline.md (255 lines) holds the original
Step 3a~8 pipeline verbatim, with a warning header naming CLI as the
source of truth and per-step CLI equivalents for cross-reference.
Read on demand only when the CLI is unavailable (offline, sandbox, etc.).
This is progressive disclosure — happy path stays in agent context every
session, fallback is fetched only when needed. The line budget (≤180 for
SKILL.md per AC-6) is met.
Refs #23
Update CLAUDE.md gotchas with the two new command-layer behaviors so
future agents understand the contract:
- bare-name specs (`ask docs add next`) are rejected at the command
layer via Gate A; users must use `npm:next` or `vercel/next.js`
- omitting a version triggers Gate B, which reads the project
lockfile (bun.lock → package-lock.json → pnpm-lock.yaml → yarn.lock
→ package.json range) to pin the installed version. Disable with
--no-manifest, require with --from-manifest.
Also update README.md examples to show the new spec grammar and remove
the now-rejected bare-name example.
Refs #23
Add test cases for @nuxt/ui@3.1.0 in bun.lock, package-lock.json, pnpm-lock.yaml, and yarn.lock to verify each parser correctly handles the leading @ in scoped package names. Refs #23
citty exposes kebab-case flags under the original key as defined in addCmd.args, so args['no-manifest'] and args['from-manifest'] are the canonical access paths. Remove the dead args.manifest===false and Record<string, unknown> camelCase casts. Refs #23
The mutation is not dead code: the ecosystem resolver fallback at ~line 365 calls resolver.resolve(parsed.name, parsed.version) directly, so parsed.version must be updated alongside effectiveSpec to pass the manifest-resolved version into the resolver. Refs #23
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
Deploying ask-registry with
|
| Latest commit: |
f089c96
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://9777e459.ask-registry.pages.dev |
| Branch Preview URL: | https://feat-add-docs-cli-split.ask-registry.pages.dev |
This was referenced Apr 8, 2026
Merged
Merged
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
addcommand now auto-resolves omitted versions from the project's lockfile/manifest (bun.lock → package-lock.json → pnpm-lock.yaml → yarn.lock → package.json range).ask docs add next) are now rejected at the command layer — users must usenpm:next(ecosystem prefix) orvercel/next.js(GitHub shorthand).skills/add-docs/SKILL.mdsplit into a CLI-call-centric happy path (137 lines, was 332) plus areferences/inline-pipeline.mdfallback for CLI-unavailable environments. CLI is now the single source of truth for the fetch/save pipeline.Why
The old add-docs skill inlined a ~332-line pipeline that mirrored
packages/cli/src/logic, creating ongoing drift risk between the two implementations. This change makes CLI the SSOT and leaves the skill to do only what LLMs are good at: intent translation (bare name → ecosystem prefix, lockfile lookup). It also guarantees downloaded docs match the version actually installed in the project, not whatever npm currently labelslatest.Breaking:
ask docs add nextused to silently auto-detect ecosystem. It now errors with a guide message. Acceptable in v0.x.Changes
c23a03b7e12ba1efd5ce1952e5e842418d6eedee53f089c96New flags
--no-manifest— skip lockfile/manifest lookup (preserves old 'latest' behavior)--from-manifest— require a manifest hit; error if package not found locallyTest Plan
bun run --cwd packages/cli build— tsc cleanbun run --cwd packages/cli test— 192 pass / 0 fail (188 pre-existing + 4 new scoped-package tests + 21 new manifest/gates tests)ask docs add next→ exits 1 with bare-name guideask docs add --no-manifest npm:zod→ manifest lookup skippedwc -l skills/add-docs/SKILL.md→ 137 (≤180)Out of scope (follow-up tracks)
ManifestHitconsumptionCloses #23
Summary by cubic
Adds a manifest gate to
@pleaseai/askCLIdocs addto auto-resolve versions from project lockfiles so downloaded docs match what’s installed. Also rejects bare-name specs and makes theadd-docsskill CLI-first to avoid drift.New Features
ecosystem:namefrom project manifests (bun.lock → package-lock.json → pnpm-lock.yaml → yarn.lock → package.json). Skip with--no-manifest; require with--from-manifest.ask docs add next). Usenpm:nextorowner/repo[@ref]instead.skills/add-docs/SKILL.mdinto a short CLI-first flow with a fallbackreferences/inline-pipeline.md.Migration
ask docs add nextwithask docs add npm:next(orvercel/next.js).--no-manifestto keep old “latest” behavior, or--from-manifestto fail if the package isn’t in your lockfile.Written for commit f089c96. Summary will update on new commits.