vanara 0.1.0 → 0.2.0

package/catalog/skills/test-plan-design/scripts/coverage-gaps.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// Runnable check: given a set of requirements and a set of test cases, report which
+// requirements have NO covering test. Maps a traceability matrix to a build gate, so an
+// untested requirement can fail CI instead of shipping silently.
+//
+// Input JSON shape:
+//   {
+//     "requirements": [ { "id": "R1", "title": "...", "priority": "high" }, ... ],
+//     "testCases":    [ { "id": "t1", "requirement": "R1" }, ... ]
+//   }
+// A test "covers" a requirement when its `requirement` field (string or array) matches the
+// requirement's `id`.
+//
+// Usage:
+//   node coverage-gaps.mjs '<json>'            # check a literal JSON string
+//   echo '<json>' | node coverage-gaps.mjs     # check from stdin
+//   node coverage-gaps.mjs --selftest          # run built-in test cases
+//
+// Exit code: 0 = every requirement is covered; 1 = gaps found / invalid input / selftest failed.
+
+export function findCoverageGaps(model) {
+  const requirements = Array.isArray(model?.requirements) ? model.requirements : [];
+  const testCases = Array.isArray(model?.testCases) ? model.testCases : [];
+
+  const covered = new Set();
+  for (const tc of testCases) {
+    const refs = Array.isArray(tc?.requirement) ? tc.requirement : [tc?.requirement];
+    for (const r of refs) {
+      if (typeof r === 'string' && r.length > 0) covered.add(r);
+    }
+  }
+
+  const gaps = requirements
+    .filter((req) => typeof req?.id === 'string')
+    .filter((req) => !covered.has(req.id))
+    .map((req) => ({ id: req.id, title: req.title ?? '', priority: req.priority ?? 'unspecified' }));
+
+  return { total: requirements.length, coveredCount: requirements.length - gaps.length, gaps };
+}
+
+function report(label, json) {
+  let model;
+  try {
+    model = typeof json === 'string' ? JSON.parse(json) : json;
+  } catch {
+    console.error(`x ${label}: invalid JSON`);
+    return false;
+  }
+  const { total, coveredCount, gaps } = findCoverageGaps(model);
+  if (gaps.length === 0) {
+    console.log(`ok ${label}: all ${total} requirement(s) covered`);
+    return true;
+  }
+  console.error(`x ${label}: ${gaps.length} of ${total} requirement(s) uncovered (${coveredCount} covered):`);
+  for (const g of gaps) {
+    console.error(`    - ${g.id} [${g.priority}] ${g.title}`.trimEnd());
+  }
+  return false;
+}
+
+function selftest() {
+  const fullCoverage = {
+    requirements: [
+      { id: 'R1', title: 'Totals include tax', priority: 'high' },
+      { id: 'R2', title: 'Expired coupons rejected', priority: 'medium' },
+    ],
+    testCases: [
+      { id: 't1', requirement: 'R1' },
+      { id: 't2', requirement: ['R1', 'R2'] }, // array form also covers R2
+    ],
+  };
+  const withGaps = {
+    requirements: [
+      { id: 'R1', title: 'Totals include tax', priority: 'high' },
+      { id: 'R2', title: 'Expired coupons rejected', priority: 'medium' },
+      { id: 'R3', title: 'Coupon min cart $50', priority: 'high' },
+    ],
+    testCases: [
+      { id: 't1', requirement: 'R1' }, // R2 and R3 left uncovered
+    ],
+  };
+
+  const a = findCoverageGaps(fullCoverage);
+  const b = findCoverageGaps(withGaps);
+
+  const checks = [
+    ['full-coverage reports zero gaps', a.gaps.length === 0],
+    ['full-coverage counts all covered', a.coveredCount === 2 && a.total === 2],
+    ['gaps case finds two gaps', b.gaps.length === 2],
+    ['gaps case identifies R2 and R3', b.gaps.map((g) => g.id).join(',') === 'R2,R3'],
+    ['gaps case counts one covered', b.coveredCount === 1 && b.total === 3],
+  ];
+
+  let allPass = true;
+  for (const [name, ok] of checks) {
+    allPass &&= ok;
+    console.log(`${ok ? 'ok' : 'x'} selftest: ${name}`);
+  }
+  process.exit(allPass ? 0 : 1);
+}
+
+const arg = process.argv[2];
+if (arg === '--selftest') selftest();
+else if (arg) process.exit(report('input', arg) ? 0 : 1);
+else {
+  let buf = '';
+  process.stdin.on('data', (c) => (buf += c));
+  process.stdin.on('end', () => process.exit(report('stdin', buf) ? 0 : 1));
+}

package/free-tier.json

@@ -0,0 +1,15 @@
+{
+  "$comment": "Items installable without a license. Everything else in the bundled catalog requires `vanara unlock <license-key>` (Pro subscription). Packs listed here imply their members are free too.",
+  "packs": ["code-review-pack", "security-pack"],
+  "agents": [
+    "code-reviewer", "pr-summarizer", "threat-modeler", "security-auditor", "vuln-scanner",
+    "debugger", "test-author", "api-designer", "refactoring-specialist", "technical-writer"
+  ],
+  "skills": [
+    "git-collaboration-workflows", "conventional-commits", "sql-index-tuning",
+    "owasp-top10", "secure-auth", "secrets-management",
+    "rest-api-design", "api-pagination", "error-handling-patterns",
+    "test-plan-design", "readme-writing", "refactoring-patterns",
+    "caching-strategies", "database-migrations", "prompt-engineering"
+  ]
+}

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "vanara",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Vanara — deploy packs of skilled AI agents. Install agents, skills, and packs into any project from the Vanara catalog.",
   "type": "module",
   "bin": {
     "vanara": "bin/vanara.js"
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "stage-catalog": "node scripts/stage-catalog.mjs --premium",
+    "prepack": "node scripts/stage-catalog.mjs"
   },
   "engines": {
     "node": ">=20"
@@ -29,10 +31,19 @@
   "files": [
     "bin/",
     "src/",
+    "catalog/",
+    "free-tier.json",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "premium-index.json"
   ],
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vanara-agents/vanara.git",
+    "directory": "cli"
+  },
+  "bugs": "https://github.com/vanara-agents/vanara/issues"
 }

package/premium-index.json

@@ -0,0 +1 @@
+[{"kind":"agent","name":"accessibility-auditor","version":"2.0.0","description":"Use when auditing an existing UI for WCAG 2.2 A/AA conformance. Investigates semantics, keyboard operability, focus, color contrast, ARIA, forms, and reduced-mo"},{"kind":"agent","name":"ai-engineer","version":"2.0.0","description":"Use PROACTIVELY when building or hardening LLM-powered features (chatbots, RAG, agents, summarizers, extractors, classifiers). Picks the right pattern (prompt →"},{"kind":"agent","name":"api-documenter","version":"2.0.0","description":"Use when documenting an HTTP/REST or GraphQL API for external or internal consumers — turning routes, schemas, or an OpenAPI spec into accurate reference docs w"},{"kind":"agent","name":"app-release-manager","version":"2.0.0","description":"Use when preparing a mobile app release or store submission. Walks through versioning, build config, store metadata, and the review-readiness checklist to avoid"},{"kind":"agent","name":"budget-planner","version":"2.0.0","description":"Use when building, reviewing, or stress-testing a budget. Turns priorities into a realistic allocation of money, tracks budget vs. actuals, forecasts cash flow "},{"kind":"agent","name":"bug-reporter","version":"2.0.0","description":"Use when a vague problem report needs to become a clean, reproducible bug ticket with numbered steps, expected vs. actual behavior, environment, severity, and a"},{"kind":"agent","name":"business-data-analyst","version":"2.0.0","description":"Use when you need to analyze a dataset or metrics and explain what they mean for the business. Pins the decision, finds the signal, quantifies the effect size, "},{"kind":"agent","name":"cicd-engineer","version":"2.0.0","description":"Use when designing, hardening, or repairing a CI/CD pipeline — build→test→scan→deploy flows, environment promotion, deployment strategies, and rollback. Reach f"},{"kind":"agent","name":"competitive-analyst","version":"2.0.0","description":"Use when analyzing competitors or sizing a market. Maps the landscape, compares positioning, pricing, and features, and surfaces gaps and opportunities — every "},{"kind":"agent","name":"compliance-auditor","version":"2.0.0","description":"Use when preparing for or assessing security compliance (SOC 2, ISO 27001, GDPR, HIPAA). Maps required controls to concrete evidence, finds gaps where a control"},{"kind":"agent","name":"component-builder","version":"2.0.0","description":"Use PROACTIVELY when building UI components. Produces accessible, reusable, responsive components with full interaction states, a documented prop/slot API, and "},{"kind":"agent","name":"content-writer","version":"2.0.0","description":"Use PROACTIVELY when creating long-form content — blog posts, articles, guides, or landing-page copy. Produces structured, on-brand writing with a clear angle a"},{"kind":"agent","name":"contract-reviewer","version":"2.0.0","description":"Use when a non-lawyer needs to understand a business contract before signing or negotiating. Produces a plain-language summary, a clause-by-clause risk read (st"},{"kind":"agent","name":"customer-success-manager","version":"2.0.0","description":"Use when driving customer onboarding, adoption, retention, or renewals. Builds outcome-based success plans, computes account health, spots churn risk early, run"},{"kind":"agent","name":"data-modeler","version":"2.0.0","description":"Use when designing a database schema or data model from scratch or reshaping an existing one — turning entities, relationships, and real access patterns into no"},{"kind":"agent","name":"data-pipeline-engineer","version":"2.0.0","description":"Use when building, reviewing, or fixing a data pipeline (ETL/ELT, batch or streaming). Produces idempotent, observable pipelines with explicit schema contracts,"},{"kind":"agent","name":"data-quality-auditor","version":"2.0.0","description":"Use when validating a dataset before analysis, reporting, or model training. Profiles the data across six quality dimensions, applies explicit rules and thresho"},{"kind":"agent","name":"database-administrator","version":"2.0.0","description":"Use when operating, hardening, or troubleshooting a production database — backups and restore drills, replication and failover, slow-query and lock investigatio"},{"kind":"agent","name":"dependency-upgrader","version":"1.0.0","description":"Dependency upgrade specialist. Use PROACTIVELY on a schedule or when audits flag vulnerable/outdated packages. Scans the dependency tree, classifies upgrades by"},{"kind":"agent","name":"e2e-test-author","version":"2.0.0","description":"Use when you need to author or stabilize end-to-end tests for critical user journeys (login, signup, checkout). Selects which flows are worth the E2E cost, driv"},{"kind":"agent","name":"email-drafter","version":"2.0.0","description":"Use when drafting or improving a professional email. Produces clear, appropriately-toned messages with a strong subject line and a single clear ask — cold outre"},{"kind":"agent","name":"embedded-developer","version":"2.0.0","description":"Use when writing firmware or embedded software for microcontrollers/RTOS. Produces resource-efficient, reliable C/C++ that respects timing, memory, and power co"},{"kind":"agent","name":"feature-builder","version":"1.0.0","description":"Vertical-slice feature specialist. Use PROACTIVELY when a feature request spans layers — data model, API, business logic, UI, and tests. Builds the complete sli"},{"kind":"agent","name":"financial-analyst","version":"2.0.0","description":"Use when analyzing financials or building a model — forecasts, budgets, scenarios, and unit economics — to support a business decision. Reads statements, comput"},{"kind":"agent","name":"game-developer","version":"2.0.0","description":"Use when building gameplay features or systems — game loops, entity/scene state, input handling, movement/physics, and mechanics. Implements simulation code tha"},{"kind":"agent","name":"game-systems-designer","version":"2.0.0","description":"Use when designing game systems and mechanics — core loops, progression, economy, difficulty, and player motivation — for engagement and long-term balance. Turn"},{"kind":"agent","name":"hr-generalist","version":"2.0.0","description":"Use when drafting HR documents and running people processes — onboarding, handbook/policy sections, performance reviews, leave/accommodation guidance, and sensi"},{"kind":"agent","name":"iac-author","version":"2.0.0","description":"Use when provisioning or changing cloud infrastructure with Terraform/Pulumi/OpenTofu. Writes idempotent, modular IaC with least-privilege IAM, remote locked st"},{"kind":"agent","name":"incident-responder","version":"2.0.0","description":"Use when an active incident or outage is declared, a pager fires, or a production regression is under live triage. Drives a calm, structured response — detect, "},{"kind":"agent","name":"integration-engineer","version":"2.0.0","description":"Use when integrating a third-party API or service (payments, email, webhooks, data sync). Builds resilient integrations with retries, idempotency, dead-letter h"},{"kind":"agent","name":"iot-systems-engineer","version":"2.0.0","description":"Use when designing an IoT system end to end — device connectivity, telemetry, fleet management, and secure firmware updates from edge to cloud. Assumes flaky ne"},{"kind":"agent","name":"it-support-specialist","version":"2.0.0","description":"Use when triaging and resolving IT support requests. Diagnoses user problems methodically, gives clear step-by-step fixes, and knows when to escalate — turning "},{"kind":"agent","name":"llm-evaluator","version":"2.0.0","description":"Use when an LLM feature's quality must become a number you can defend. Designs eval criteria, builds datasets, picks scoring (deterministic vs LLM-as-judge vs p"},{"kind":"agent","name":"meeting-summarizer","version":"2.0.0","description":"Use when turning a meeting transcript or raw notes into a concise summary with decisions, action items, and owners. Captures what was decided, not every word sa"},{"kind":"agent","name":"ml-model-reviewer","version":"2.0.0","description":"Use when reviewing an ML model, training pipeline, or model card before it ships or is promoted. Audits for data leakage, evaluation soundness, reproducibility,"},{"kind":"agent","name":"mobile-app-builder","version":"2.0.0","description":"Use PROACTIVELY when building or extending a mobile app feature (iOS, Android, or cross-platform like React Native/Flutter). Builds idiomatic, performant screen"},{"kind":"agent","name":"mobile-perf-optimizer","version":"2.0.0","description":"Use when a mobile app is slow to start, janky while scrolling, drains battery, or grows memory without bound. Profiles first to find the real bottleneck, fixes "},{"kind":"agent","name":"network-engineer","version":"2.0.0","description":"Use when designing, segmenting, or troubleshooting network connectivity — VPCs, subnets, VLSM addressing, routing, switching, firewalls/security groups, DNS, an"},{"kind":"agent","name":"network-troubleshooter","version":"2.0.0","description":"Use when diagnosing a connectivity problem — timeouts, connection refused, DNS failures, TLS/cert errors, intermittent packet loss, or an unreachable service. W"},{"kind":"agent","name":"observability-engineer","version":"2.0.0","description":"Use when instrumenting a service for production, defining SLOs, designing alerts, or debugging a live incident. Designs the three pillars (logs, metrics, traces"},{"kind":"agent","name":"perf-optimizer","version":"2.0.0","description":"Use when a page, endpoint, query, or job is slow or a bundle is too large. Profiles first to locate the dominant cost, then proposes prioritized, measurable fix"},{"kind":"agent","name":"performance-engineer","version":"2.0.0","description":"Use when a backend, service, or job is slow, resource-heavy, or missing a latency/throughput SLO. Measures first, finds the dominant bottleneck, fixes it, and p"},{"kind":"agent","name":"policy-drafter","version":"2.0.0","description":"Use when drafting a first version of an internal business policy or governance document (acceptable use, information security, PTO, code of conduct). Produces a"},{"kind":"agent","name":"privacy-engineer","version":"2.0.0","description":"Use when handling personal data or implementing privacy requirements (GDPR, CCPA). Maps data flows, applies privacy-by-design and data minimization, classifies "},{"kind":"agent","name":"product-manager","version":"2.0.0","description":"Use when deciding what to build and why — turning user problems and business goals into a prioritized roadmap, a crisp PRD, and measurable success metrics. Best"},{"kind":"agent","name":"project-planner","version":"2.0.0","description":"Use PROACTIVELY when turning a goal into an executable project plan — when you need a scoped work breakdown, estimates, a dependency-aware schedule with a criti"},{"kind":"agent","name":"prompt-engineer","version":"2.0.0","description":"Use when a prompt is unreliable, inconsistent, or being written from scratch. Designs clear, structured prompts (role, task, constraints, few-shot, output schem"},{"kind":"agent","name":"proposal-writer","version":"2.0.0","description":"Use when writing a sales proposal, quote, or statement of work. Produces a clear, persuasive, buyer-centric document tied to the prospect's goals, scope, and va"},{"kind":"agent","name":"qa-strategist","version":"2.0.0","description":"Use when planning how to test a feature, sprint, or release — when you need a risk-based test strategy rather than just more tests. Designs coverage across unit"},{"kind":"agent","name":"recruiter","version":"2.0.0","description":"Use when hiring for a role — clarifying the req with the hiring manager, writing inclusive job descriptions, sourcing and outreach, and running a structured, bi"},{"kind":"agent","name":"requirements-analyst","version":"2.0.0","description":"Use when a request is vague, a feature is just starting, or stakeholders disagree on scope. Turns fuzzy asks into clear, testable requirements — problem stateme"},{"kind":"agent","name":"research-synthesizer","version":"2.0.0","description":"Use when you need to gather and synthesize information from multiple sources into a clear, cited, decision-ready brief. Triangulates across sources, surfaces wh"},{"kind":"agent","name":"sales-call-prepper","version":"2.0.0","description":"Use when preparing for a sales call, demo, or discovery meeting. Builds a complete call-prep brief — account research, a single call objective, discovery questi"},{"kind":"agent","name":"sales-outreach-writer","version":"2.0.0","description":"Use when writing cold outreach (email, LinkedIn) to prospects. Produces personalized, concise messages that lead with the prospect's problem, make a single low-"},{"kind":"agent","name":"seo-optimizer","version":"2.0.0","description":"Use when optimizing content or a page for search. Improves on-page SEO — title, meta, headings, internal links, and intent match — plus technical basics and str"},{"kind":"agent","name":"smart-contract-auditor","version":"2.0.0","description":"Use when reviewing a smart contract for security before deployment. Thinks adversarially about value and trust, hunts reentrancy, access-control flaws, overflow"},{"kind":"agent","name":"smart-contract-developer","version":"2.0.0","description":"Use when writing or modifying blockchain smart contracts (Solidity/EVM). Implements correct, gas-efficient contracts with security first — invariants, checks-ef"},{"kind":"agent","name":"social-media-manager","version":"2.0.0","description":"Use when planning or writing social posts across platforms. Adapts one message into platform-native posts (X, LinkedIn, Instagram, TikTok) with the right tone, "},{"kind":"agent","name":"solution-architect","version":"2.0.0","description":"Use when planning a new system or feature, evaluating architectural trade-offs between options, choosing technologies, or writing an ADR. Gathers functional + n"},{"kind":"agent","name":"support-responder","version":"2.0.0","description":"Use when drafting a reply to a customer support ticket. Writes clear, empathetic responses that acknowledge the person, deliver an accurate answer or fix, set h"},{"kind":"agent","name":"sysadmin-automator","version":"2.0.0","description":"Use when administering or automating servers and systems. Writes safe, idempotent shell/automation scripts for provisioning, maintenance, backups, scheduling, a"},{"kind":"agent","name":"tech-spec-writer","version":"2.0.0","description":"Use when a feature or change needs a written design before coding — to align a team, surface alternatives, and de-risk rollout. Produces a concise technical spe"},{"kind":"agent","name":"user-researcher","version":"2.0.0","description":"Use when you need to understand users — planning interviews, surveys, or usability tests, writing unbiased questions, recruiting representative participants, an"},{"kind":"skill","name":"app-store-optimization","version":"2.0.0","description":"How to optimize an app-store listing (ASO) for discovery and conversion — title, subtitle, keywords, screenshots, icon, ratings, and the metadata that drives in"},{"kind":"skill","name":"audit-logging","version":"2.0.0","description":"Design tamper-evident audit logs that satisfy security and compliance — what to record (who/what/when/where/outcome), what to never log (secrets/PII), structure"},{"kind":"skill","name":"background-jobs","version":"1.0.0","description":"Design background job systems that don't lose or double work — enqueue-after-commit, retry policies with jitter, idempotent handlers, visibility timeouts, prior"},{"kind":"skill","name":"backup-and-recovery","version":"2.0.0","description":"Design and operate a tested backup and disaster-recovery strategy — the 3-2-1 rule, RPO/RTO targets, full vs incremental vs differential, point-in-time recovery"},{"kind":"skill","name":"c4-diagramming","version":"2.0.0","description":"Document software architecture with the C4 model (Context, Container, Component, Code) as text-based diagrams in version control. Covers the four abstraction le"},{"kind":"skill","name":"changelog-writing","version":"2.0.0","description":"How to write and maintain a changelog humans actually read — Keep a Changelog structure, an Unreleased section, the six standard categories (Added/Changed/Depre"},{"kind":"skill","name":"churn-prevention","version":"2.0.0","description":"How to reduce customer churn — separating voluntary from involuntary churn, scoring account health from leading signals, running save and win-back plays, and fi"},{"kind":"skill","name":"ci-pipeline-design","version":"2.0.0","description":"Design fast, reliable CI/CD pipelines — fail-fast staged checks (lint→test→build→scan→deploy), dependency and build caching, artifact passing, matrix builds, me"},{"kind":"skill","name":"cloud-cost-optimization","version":"1.0.0","description":"Cut cloud spend without cutting reliability — rightsizing from utilization data, spot and commitment strategy, storage lifecycle rules, egress traps, tagging fo"},{"kind":"skill","name":"cold-outreach","version":"2.0.0","description":"How to write cold outreach that earns replies — relevance-first openers, specific personalization, one low-friction ask, tight subject lines, and a graceful fol"},{"kind":"skill","name":"content-calendar","version":"2.0.0","description":"How to plan and run a content calendar that balances pillars, formats, and channels around goals — cadence design, content mix, batching and repurposing, and a "},{"kind":"skill","name":"contract-review","version":"2.0.0","description":"How to read a business contract for the terms that matter most — liability, indemnity, IP, termination, payment, and auto-renewal — and spot red flags. Deep ref"},{"kind":"skill","name":"copywriting-frameworks","version":"2.0.0","description":"Proven copywriting frameworks (AIDA, PAS, BAB, FAB, the 4 Ps/4 Us) and when to use each to structure persuasive marketing copy. A deep reference with worked bef"},{"kind":"skill","name":"data-modeling","version":"2.0.0","description":"Design data models that make invalid states impossible — entities & relationships, normalization (1NF–3NF) vs deliberate denormalization, keys & indexing, relat"},{"kind":"skill","name":"data-storytelling","version":"2.0.0","description":"Turn data into a decision — lead with the insight, choose the right chart for the intent, frame it for the audience, and drive to an action. A deep reference wi"},{"kind":"skill","name":"data-validation","version":"2.0.0","description":"Validate untrusted data at boundaries with schema-based contracts — types, ranges, enums, regex, uniqueness, referential integrity, freshness — so bad input is "},{"kind":"skill","name":"database-scaling","version":"2.0.0","description":"Scale a relational database under growing load in the right order — query/index tuning, connection pooling, read replicas and replication lag, caching, table pa"},{"kind":"skill","name":"deployment-strategies","version":"1.0.0","description":"Deploy without fear — blue-green vs canary vs rolling trade-offs, database migrations during deploys (expand/contract), rollback design and its limits, smoke te"},{"kind":"skill","name":"dns-configuration","version":"2.0.0","description":"How DNS actually works and how to change it safely — record types (A/AAAA/CNAME/MX/TXT/NS/SOA/CAA), TTL and propagation, the CNAME-at-apex problem, email auth ("},{"kind":"skill","name":"dockerfile-authoring","version":"2.0.0","description":"Author small, secure, fast-building container images — multi-stage builds, layer caching, non-root/distroless hardening, .dockerignore, size optimization, and H"},{"kind":"skill","name":"documentation-structure","version":"2.0.0","description":"How to architect a documentation set with the Diátaxis framework — separating tutorials, how-to guides, reference, and explanation, then wiring information arch"},{"kind":"skill","name":"e2e-playwright","version":"2.0.0","description":"Deep reference for reliable Playwright E2E tests — role/accessible locators over CSS, web-first assertions and auto-waiting (no hard sleeps), fixtures and stora"},{"kind":"skill","name":"event-driven-architecture","version":"1.0.0","description":"Design event-driven systems that stay consistent — queues vs streams, pub/sub topology, idempotent consumers, the transactional outbox, sagas for multi-service "},{"kind":"skill","name":"feature-engineering","version":"2.0.0","description":"Engineer ML features safely and effectively — feature types, encoding (one-hot/target/ordinal), scaling, missing-value and outlier handling, feature selection, "},{"kind":"skill","name":"feature-flags-experimentation","version":"1.0.0","description":"Ship behind flags and learn from experiments — progressive rollouts, kill switches, deterministic bucketing, flag lifecycle and debt cleanup, A/B test design wi"},{"kind":"skill","name":"financial-modeling","version":"2.0.0","description":"How to build a clear, drivable financial model — three-statement linkage, driver-based forecasting, explicit assumptions, scenarios, sensitivity, and cash runwa"},{"kind":"skill","name":"frontend-state-management","version":"2.0.0","description":"Choose the right home for every piece of frontend state — server, client, URL, form, and derived — so React/TS apps stay predictable and never store the same tr"},{"kind":"skill","name":"game-loop-architecture","version":"2.0.0","description":"Structure a robust game loop — fixed vs variable timestep, the \"fix your timestep\" accumulator, decoupling update from render with interpolation, determinism fo"},{"kind":"skill","name":"game-performance","version":"2.0.0","description":"Keep games at a stable frame rate. Use when a game stutters, drops frames, or hitches — budgeting the 16.6ms frame, profiling CPU vs GPU bottlenecks, object poo"},{"kind":"skill","name":"gdpr-compliance","version":"2.0.0","description":"Build core GDPR obligations into software — lawful basis, data-subject rights (access/erasure/portability/rectification), consent, data minimization, processor/"},{"kind":"skill","name":"graphql-api-design","version":"1.0.0","description":"Design GraphQL APIs that survive production — schema modeling, resolver patterns, the N+1 problem and dataloaders, connection-style pagination, error handling, "},{"kind":"skill","name":"incident-management","version":"2.0.0","description":"Run a production incident from detection to postmortem — severity classification & SLAs, roles (Incident Commander, comms, ops), the detect→triage→mitigate→reso"},{"kind":"skill","name":"internationalization","version":"1.0.0","description":"Internationalize correctly from the start — ICU MessageFormat and plural rules, RTL layouts with logical CSS properties, locale-aware dates/numbers/currency via"},{"kind":"skill","name":"interview-design","version":"2.0.0","description":"Designing structured hiring interviews that predict job performance fairly — competency modeling, behavioral/STAR question design, consistent scoring rubrics, i"},{"kind":"skill","name":"iot-connectivity","version":"2.0.0","description":"Connect IoT fleets reliably — choosing MQTT/CoAP/HTTP/LoRaWAN, MQTT QoS and topic design, device provisioning and identity, OTA updates, surviving intermittent "},{"kind":"skill","name":"job-description-writing","version":"2.0.0","description":"How to write job descriptions that attract strong, diverse candidates — outcome-focused responsibilities, realistic must-have vs nice-to-have requirements, incl"},{"kind":"skill","name":"knowledge-base-writing","version":"2.0.0","description":"How to write self-service help articles that deflect tickets — task-focused titles, findable structure, clear steps, and maintenance loops. A deep reference wit"},{"kind":"skill","name":"kubernetes-manifests","version":"2.0.0","description":"Conventions for writing production-grade Kubernetes manifests — Deployments, Services, Ingress, liveness/readiness/startup probes, resource requests/limits and "},{"kind":"skill","name":"legacy-modernization","version":"1.0.0","description":"Modernize legacy systems without a rewrite bet — strangler-fig migration, finding seams, characterization tests before touching anything, anti-corruption layers"},{"kind":"skill","name":"linux-administration","version":"2.0.0","description":"Operating Linux servers with confidence — users/groups and octal permissions (setuid/setgid/sticky), systemd units and journald, process/disk/network triage (ps"},{"kind":"skill","name":"llm-evaluation","version":"2.0.0","description":"Deep, practical guide to evaluating LLM outputs — building eval datasets, choosing reference-based vs LLM-as-judge vs pairwise/Elo vs human scoring, picking met"},{"kind":"skill","name":"load-balancing","version":"2.0.0","description":"Distribute traffic across instances for scale and reliability — L4 vs L7, algorithms (round-robin, weighted, least-connections, consistent-hash), active/passive"},{"kind":"skill","name":"market-research","version":"2.0.0","description":"How to size and understand a market without fooling yourself — TAM/SAM/SOM sizing, customer segmentation, competitive analysis, and combining secondary and prim"},{"kind":"skill","name":"mcp-server-development","version":"1.0.0","description":"Build MCP servers agents can actually use — tool schema design that models route correctly, resources vs tools vs prompts, stdio and HTTP transports, auth patte"},{"kind":"skill","name":"meeting-notes-structure","version":"2.0.0","description":"How to structure meeting notes so they drive action afterward — separating decisions from discussion, capturing action items with an owner and due date every ti"},{"kind":"skill","name":"mobile-ui-patterns","version":"2.0.0","description":"Platform-aware mobile UI patterns for iOS and Android — navigation (tabs/stack/drawer), touch targets and thumb zones, gestures and feedback, safe areas and not"},{"kind":"skill","name":"model-evaluation","version":"2.0.0","description":"How to evaluate ML models honestly — task-appropriate metrics (classification vs regression), train/val/test splits and cross-validation, baselines, confusion m"},{"kind":"skill","name":"objection-handling","version":"2.0.0","description":"How to handle sales objections honestly and effectively — acknowledge, clarify the real concern, reframe with evidence, and confirm. Covers price, timing, trust"},{"kind":"skill","name":"offline-sync","version":"2.0.0","description":"Build offline-first apps that work without a connection — local-first reads, an outbox/mutation queue, optimistic UI, idempotent replay on reconnect, delta sync"},{"kind":"skill","name":"okr-writing","version":"2.0.0","description":"How to write effective OKRs — qualitative objectives paired with measurable key results — that drive focus instead of becoming a task list. A deep reference wit"},{"kind":"skill","name":"payment-integration","version":"1.0.0","description":"Integrate payments without losing money — idempotency keys on every charge, webhook-driven state (never redirect-driven), PCI scope boundaries, SCA/3DS flows, s"},{"kind":"skill","name":"performance-review-writing","version":"2.0.0","description":"How to write fair, useful performance reviews — specific evidence over vague impressions, behavior-based feedback (SBI/STAR), balanced strengths and growth area"},{"kind":"skill","name":"pricing-strategy","version":"2.0.0","description":"How to set and structure pricing — value-based pricing, good-better-best tiering and packaging, psychological anchoring, discounting, and price testing — to cap"},{"kind":"skill","name":"prioritization-frameworks","version":"2.0.0","description":"Decision frameworks for prioritizing product and engineering work — RICE, ICE, MoSCoW, Kano, weighted scoring, and Cost of Delay / WSJF — with guidance on which"},{"kind":"skill","name":"privacy-policy-drafting","version":"2.0.0","description":"How to draft a privacy policy that is accurate, readable, and covers the required elements — what data you collect, why, legal basis, sharing, retention, and us"},{"kind":"skill","name":"product-metrics","version":"2.0.0","description":"Choosing and operating product metrics that reflect real value — North Star definition, the AARRR pirate funnel, activation/retention/engagement, leading vs lag"},{"kind":"skill","name":"rag-patterns","version":"2.0.0","description":"Deep, practical guide to retrieval-augmented generation that actually grounds answers — chunking, embeddings, vector + hybrid/BM25 search, reranking, context as"},{"kind":"skill","name":"realtime-communication","version":"1.0.0","description":"Build realtime features that survive production — WebSockets vs SSE vs polling trade-offs, connection lifecycle, reconnect with backoff and event resume, heartb"},{"kind":"skill","name":"regression-strategy","version":"2.0.0","description":"Design a fast, trustworthy regression strategy — turn every fixed bug into a permanent test, tier suites (smoke/full/nightly), select only impacted tests via te"},{"kind":"skill","name":"responsive-layout","version":"2.0.0","description":"Build fluid, responsive web layouts from 320px to ultrawide with modern CSS — mobile-first, fluid type/space via clamp(), intrinsic CSS grid/flex, container que"},{"kind":"skill","name":"roadmap-planning","version":"2.0.0","description":"How to build a product roadmap that communicates strategy — outcome-based themes over feature lists, Now/Next/Later horizons, prioritization, and honest time fr"},{"kind":"skill","name":"rtos-firmware-patterns","version":"2.0.0","description":"RTOS firmware patterns — preemptive priority scheduling, ISR discipline (short handlers, deferred work, ISR-safe APIs), queues/semaphores/mutexes, priority inve"},{"kind":"skill","name":"runbook-writing","version":"2.0.0","description":"Write operational runbooks an on-call engineer can follow at 3am with zero context — exact triggers, preconditions, numbered copy-pasteable steps, per-step veri"},{"kind":"skill","name":"sales-discovery","version":"2.0.0","description":"How to run effective sales discovery — qualification frameworks (BANT, MEDDIC), SPIN questioning, quantifying pain, and mapping the decision process. A deep ref"},{"kind":"skill","name":"search-implementation","version":"1.0.0","description":"Implement search that finds things — full-text mechanics (analyzers, BM25), vector/semantic search and hybrid ranking with RRF, relevance evaluation with golden"},{"kind":"skill","name":"seo-on-page","version":"2.0.0","description":"On-page SEO — search-intent matching, title tags, meta descriptions, heading structure, internal linking, URLs, image alt text, and structured data that ranks w"},{"kind":"skill","name":"slo-error-budgets","version":"1.0.0","description":"Define reliability numerically — choosing SLIs users actually feel, setting SLO targets, error budgets and multi-window burn-rate alerting, latency percentiles "},{"kind":"skill","name":"smart-contract-security","version":"2.0.0","description":"Deep reference for securing Solidity/EVM smart contracts — reentrancy, access control, oracle/price manipulation, integer over/underflow, delegatecall, unchecke"},{"kind":"skill","name":"soc2-readiness","version":"2.0.0","description":"Get audit-ready for SOC 2 — scope the Trust Services Criteria, build a controls-to-evidence matrix, write the policies auditors check, choose Type I vs Type II,"},{"kind":"skill","name":"solidity-patterns","version":"2.0.0","description":"Battle-tested Solidity/EVM patterns for safe smart contracts — checks-effects-interactions, reentrancy guards, access control (Ownable/roles), pull-over-push pa"},{"kind":"skill","name":"source-evaluation","version":"2.0.0","description":"How to judge whether a source deserves trust before you cite it — authority, evidence, currency, bias, and corroboration — using the CRAAP test, primary-vs-seco"},{"kind":"skill","name":"support-response-writing","version":"2.0.0","description":"How to write support replies that resolve and reassure — acknowledgement and empathy, clear solutions or honest next steps, expectation-setting, de-escalation, "},{"kind":"skill","name":"system-design-patterns","version":"2.0.0","description":"Deep reference for scaling systems — load balancers, caches, queues, replicas, sharding, CDNs, CAP and consistency models, idempotency, and back-of-envelope cap"},{"kind":"skill","name":"tcp-ip-fundamentals","version":"2.0.0","description":"The networking fundamentals every engineer needs — the layered model and encapsulation, IPv4 addressing/subnetting/CIDR, TCP vs UDP, the 3-way handshake and con"},{"kind":"skill","name":"terms-of-service","version":"2.0.0","description":"How to draft terms of service covering the essentials — acceptable use, accounts, payment, liability limits, indemnification, termination, changes, governing la"},{"kind":"skill","name":"unit-economics","version":"2.0.0","description":"Analyze unit economics — CAC, LTV, contribution margin, and CAC payback — to judge whether a business model actually makes money per customer. A deep reference "},{"kind":"skill","name":"user-interview-design","version":"2.0.0","description":"How to design and run user (product/UX) research interviews that yield honest insight — non-leading questions, past-behavior focus, participant recruiting, bias"},{"kind":"skill","name":"user-story-writing","version":"2.0.0","description":"How to write user stories and acceptance criteria that are small, testable, and valuable — using INVEST, Given-When-Then, and disciplined story splitting. A dee"},{"kind":"skill","name":"wcag-accessibility","version":"2.0.0","description":"Deep, practical reference for building WCAG 2.2 AA-conformant web UIs — POUR principles, semantic HTML, keyboard operability and visible focus, ARIA done right,"},{"kind":"skill","name":"webhook-design","version":"2.0.0","description":"Design and consume webhooks reliably — HMAC signature verification, timestamp/replay protection, fast 2xx acknowledgement, consumer idempotency via event-id ded"},{"kind":"pack","name":"ai-llm-pack","version":"2.0.0","description":"Build reliable LLM-powered features — prompt engineering, RAG, agents, and evaluation — with quality and cost under control."},{"kind":"pack","name":"ai-product-builder-pack","version":"2.0.0","description":"A combo pack for shipping AI-powered products — decide the bet, engineer the prompt, ground it with retrieval, expose a clean API, and prove quality with evals."},{"kind":"pack","name":"architecture-analysis-pack","version":"2.0.0","description":"The front of the build pipeline — turn a fuzzy ask into testable requirements, a justified architecture, and a spec engineering can build from, before a line of"},{"kind":"pack","name":"backend-essentials-pack","version":"2.0.0","description":"Everything a backend developer needs to design, build, test, review, and ship server-side code with confidence — API design, safe migrations, and query performa"},{"kind":"pack","name":"business-ops-pack","version":"2.0.0","description":"Run the day-to-day better — set measurable goals, turn them into a prioritized plan, keep meetings decision-focused, and communicate clearly. Bundles the operat"},{"kind":"pack","name":"compliance-grc-pack","version":"2.0.0","description":"Get and stay compliant — SOC 2 and ISO readiness, GDPR/privacy engineering, and the tamper-evident audit logging that proves it. Sequences the agents and skills"},{"kind":"pack","name":"craftsmanship-pack","version":"2.0.0","description":"Keep a codebase healthy as it grows — safe refactoring, measured performance work, and resilient third-party integrations, sequenced so you change structure, sp"},{"kind":"pack","name":"customer-success-pack","version":"2.0.0","description":"Keep customers happy and retained — empathetic support replies, churn prevention, success management, and a self-service knowledge base, sequenced into one life"},{"kind":"pack","name":"data-ml-pack","version":"2.0.0","description":"Build trustworthy data and ML systems — reliable pipelines, validated data, leakage-free features, and honest model evaluation, sequenced from raw source to a m"},{"kind":"pack","name":"database-pack","version":"2.0.0","description":"Design and operate databases that stay correct, durable, and fast — schema modeling, tested backups and recovery, and scaling in the right order. Sequences the "},{"kind":"pack","name":"devops-cloud-pack","version":"2.0.0","description":"Everything between \"code is written\" and \"it runs reliably in production\" — containers, infrastructure-as-code, CI/CD pipelines, Kubernetes, and observability t"},{"kind":"pack","name":"embedded-iot-pack","version":"2.0.0","description":"Build connected devices end to end — resource-efficient firmware, real-time RTOS patterns, and reliable, secure IoT connectivity from the microcontroller to the"},{"kind":"pack","name":"finance-pack","version":"2.0.0","description":"Turn numbers into decisions — driver-based models, budgets and runway, unit economics, and pricing. Sequences finance agents and skills into one repeatable plan"},{"kind":"pack","name":"founder-operations-pack","version":"2.0.0","description":"A combo pack for running the business side of a startup — set product direction, keep the unit economics honest, price the product, hire well, and get a first-p"},{"kind":"pack","name":"frontend-essentials-pack","version":"2.0.0","description":"Everything a frontend developer needs to ship fast, accessible, responsive interfaces that look intentional — component design, state placement, WCAG audit, and"},{"kind":"pack","name":"full-stack-developer-pack","version":"2.0.0","description":"A combo pack for full-stack developers — design the API, build the UI, test-drive it, and ship it clean. Bundles the frontend and backend essentials with qualit"},{"kind":"pack","name":"game-dev-pack","version":"2.0.0","description":"Build games that play well and run smoothly — systems design, gameplay implementation, a solid game-loop architecture, and stable frame rate. Sequences design, "},{"kind":"pack","name":"go-to-market-pack","version":"2.0.0","description":"A combo pack to take a product to market — content and SEO, sales outreach and proposals, and customer success to retain what you win. Sequences attract, conver"},{"kind":"pack","name":"it-operations-pack","version":"2.0.0","description":"Keep systems running and users unblocked — incident response, server automation, and IT support, sequenced into repeatable ops workflows with runbooks that make"},{"kind":"pack","name":"knowledge-worker-pack","version":"2.0.0","description":"A combo pack for non-developers — set goals, plan the work, research and analyze to back decisions, write the output, and keep meetings tight. The essentials of"},{"kind":"pack","name":"legal-pack","version":"2.0.0","description":"Get a fast, clear first pass on everyday business legal documents — contract review, privacy policies, and terms of service — structured so you can hand a well-"},{"kind":"pack","name":"marketing-content-pack","version":"2.0.0","description":"Everything to plan, write, optimize, and distribute content that ranks and converts — a content engine that sequences long-form writing, on-page SEO, and platfo"},{"kind":"pack","name":"mobile-pack","version":"2.0.0","description":"Build, optimize, and ship mobile apps — native-feeling features, smooth performance, offline support, and a clean path through app-store review. Sequences the m"},{"kind":"pack","name":"networking-pack","version":"2.0.0","description":"Design and debug networks — topology and firewalls, DNS, load balancing, and methodical connectivity troubleshooting."},{"kind":"pack","name":"people-pack","version":"2.0.0","description":"Hire and manage people well — inclusive job descriptions, structured bias-resistant interviews, fair evidence-based performance reviews, and clear HR documents,"},{"kind":"pack","name":"product-management-pack","version":"2.0.0","description":"Decide what to build and why — user research, outcome-based roadmaps, and product metrics that focus the team on real value. Sequences discovery, prioritization"},{"kind":"pack","name":"qa-testing-pack","version":"2.0.0","description":"Catch bugs before users do — risk-based test strategy, reliable end-to-end tests, clean bug reports, and a regression suite that keeps main green. Sequences the"},{"kind":"pack","name":"research-analysis-pack","version":"2.0.0","description":"Turn questions into decisions — synthesize credible research, size markets, scan competitors, analyze your own metrics, and tell the story that drives action. O"},{"kind":"pack","name":"sales-pack","version":"2.0.0","description":"Win more deals — personalized cold outreach, effective discovery, prepared calls, confident objection handling, and persuasive proposals, sequenced into one rep"},{"kind":"pack","name":"secure-delivery-pack","version":"2.0.0","description":"A combo pack for shipping safely at speed — CI/CD, security auditing, dependency and secret scanning, risk-based test strategy, and observability, sequenced int"},{"kind":"pack","name":"sre-reliability-pack","version":"1.0.0","description":"Run production like an SRE team — SLOs and error budgets as the decision system, burn-rate alerting, canary deploys with rollback discipline, incident response "},{"kind":"pack","name":"startup-launch-pack","version":"2.0.0","description":"A combo pack for founders taking a product from idea to launch — scope it, architect it lean, build the UI and API, get auth right, and pass a security audit be"},{"kind":"pack","name":"technical-writing-pack","version":"2.0.0","description":"Produce documentation developers and users actually follow — structure the docs set, write task-oriented guides, document the API from source, and keep a clean "},{"kind":"pack","name":"web3-pack","version":"2.0.0","description":"Build and secure blockchain smart contracts — correct, gas-aware Solidity development paired with adversarial security auditing, sequenced from spec to audited "}]

package/src/config.js

@@ -1,6 +1,8 @@
 // Central constants and source resolution. No hardcoded secrets, no network in v0.1.
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import os from 'node:os';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export const CLI_ROOT = path.resolve(__dirname, '..');
@@ -12,10 +14,17 @@ export const LOCKFILE = '.vanara.json';
 //   1. --source <dir> flag
 //   2. VANARA_REGISTRY env var (a directory today; an https registry URL in v1
 //      once the hosted registry + entitlements exist — see OPEN-CORE-PLAN.md §3)
-//   3. dev default: the sibling forge catalog in this repo
+//   3. the catalog bundled inside this npm package (works for ANY npx user)
+//   4. dev default: the sibling forge catalog in this repo
+export const PREMIUM_DIR = path.join(os.homedir(), '.vanara', 'catalog');
+
 export function resolveSource(flagValue) {
   if (flagValue) return flagValue;
   if (process.env.VANARA_REGISTRY) return process.env.VANARA_REGISTRY;
+  // Unlocked subscribers have the full catalog synced locally (vanara unlock/sync).
+  if (existsSync(path.join(PREMIUM_DIR, 'packs'))) return PREMIUM_DIR;
+  const bundled = path.join(CLI_ROOT, 'catalog');
+  if (existsSync(path.join(bundled, 'packs'))) return bundled;
   return path.resolve(CLI_ROOT, '..', 'forge', 'catalog');
 }
 
@@ -25,3 +34,24 @@ export const CLAUDE_TARGET = {
   agentsDir: path.join('.claude', 'agents'),
   skillsDir: path.join('.claude', 'skills'),
 };
+
+// Pro subscription rail — Polar.sh (merchant of record; public license validation,
+// so no secrets live in this CLI). organizationId + checkoutUrl are filled in
+// when the store goes live; VANARA_POLAR_ORG env overrides for testing.
+export const POLAR = {
+  apiBase: 'https://api.polar.sh',
+  organizationId: 'ede2a514-fe80-4b64-b9e6-ce7985c9fb91',
+  checkoutUrl: 'https://buy.polar.sh/polar_cl_nsNsLMyGBcKWwn3IWgCbvvFnFJePiDWZvSYd13zaosm',
+  // Gated premium-catalog endpoint (Cloudflare Worker in ../worker validates the
+  // license key server-side with Polar, then streams the tarball).
+  premiumUrl: 'https://get.vanaraagents.com/premium',
+};
+
+// Free-tier manifest bundled with the package.
+export function loadFreeTier() {
+  try {
+    return JSON.parse(readFileSync(path.join(CLI_ROOT, 'free-tier.json'), 'utf8'));
+  } catch {
+    return { packs: [], agents: [], skills: [] };
+  }
+}

package/src/license.js

@@ -0,0 +1,143 @@
+// Pro licensing — Polar.sh license keys as the rented entitlement service.
+// Validation uses Polar's PUBLIC validate endpoint: no secrets ship in this CLI
+// and no backend of ours exists. Free tier never touches this module.
+// Mini version of OPEN-CORE-PLAN §3.2: cached validation, weekly re-check,
+// 7-day offline grace. Client-side checks are honest friction by design —
+// real enforcement arrives with the registry (Phase 3).
+import { mkdir, readFile, writeFile, rm } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { POLAR, PREMIUM_DIR } from './config.js';
+import { execFileSync } from 'node:child_process';
+import { createWriteStream } from 'node:fs';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+const DAY_MS = 86_400_000;
+const REVALIDATE_AFTER_MS = 7 * DAY_MS;   // check weekly when online
+const OFFLINE_GRACE_MS = 7 * DAY_MS;      // beyond revalidation window
+
+export const licenseFilePath = (home = os.homedir()) =>
+  path.join(home, '.vanara', 'license.json');
+
+/** Reject archives whose members escape the extraction dir (zip-slip). */
+export function assertSafeTar(listing) {
+  for (const raw of listing.split(/\r?\n/)) {
+    const entry = raw.trim();
+    if (!entry) continue;
+    const unsafe =
+      entry.startsWith('/') ||
+      /^[A-Za-z]:/.test(entry) ||               // C:\ absolute
+      entry.split(/[\\/]/).some((seg) => seg === '..');
+    if (unsafe) {
+      throw new Error(`Refusing to extract unsafe archive path: ${entry}`);
+    }
+  }
+}
+
+export async function readLicense(fileOverride) {
+  try {
+    return JSON.parse(await readFile(fileOverride ?? licenseFilePath(), 'utf8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+async function writeLicense(record, fileOverride) {
+  const file = fileOverride ?? licenseFilePath();
+  // The license key is a bearer credential — keep the dir + file owner-only
+  // (no-op on Windows ACLs, real protection on POSIX shared machines).
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  await writeFile(file, `${JSON.stringify(record, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+}
+
+export async function clearLicense(fileOverride) {
+  await rm(fileOverride ?? licenseFilePath(), { force: true });
+}
+
+/** Validate a key against Polar's public endpoint. Returns { valid, error? }. */
+export async function validateWithPolar(key, { fetchFn = fetch } = {}) {
+  const orgId = process.env.VANARA_POLAR_ORG ?? POLAR.organizationId;
+  if (!orgId) {
+    return { valid: false, error: 'Store not configured yet (missing Polar organization id).' };
+  }
+  try {
+    const res = await fetchFn(`${POLAR.apiBase}/v1/customer-portal/license-keys/validate`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ key, organization_id: orgId }),
+    });
+    if (res.status === 404) return { valid: false, error: 'License key not found.' };
+    if (!res.ok) return { valid: false, error: `Validation service returned ${res.status}.`, transient: res.status >= 500 };
+    const data = await res.json();
+    const status = (data.status ?? '').toLowerCase();
+    if (['granted', 'active', 'valid'].includes(status)) return { valid: true };
+    return { valid: false, error: `License is ${status || 'not active'} (expired or cancelled subscription).` };
+  } catch (err) {
+    return { valid: false, error: `Could not reach the license service: ${err.message}`, transient: true };
+  }
+}
+
+/** vanara unlock <key> — validate online, persist on success. */
+export async function unlock(key, { fetchFn, fileOverride } = {}) {
+  const result = await validateWithPolar(key, { fetchFn });
+  if (!result.valid) return result;
+  await writeLicense({ key, validatedAt: new Date().toISOString(), plan: 'pro' }, fileOverride);
+  return { valid: true };
+}
+
+/**
+ * Is Pro currently unlocked? Uses the cached validation; revalidates in the
+ * background window; tolerates being offline for the grace period. Never
+ * blocks an install on a transient network failure inside the grace window.
+ */
+export async function isUnlocked({ fetchFn, fileOverride, now = Date.now() } = {}) {
+  const lic = await readLicense(fileOverride);
+  if (!lic?.key) return { unlocked: false };
+  const age = now - Date.parse(lic.validatedAt ?? 0);
+  if (age < REVALIDATE_AFTER_MS) return { unlocked: true, plan: lic.plan };
+
+  const result = await validateWithPolar(lic.key, { fetchFn });
+  if (result.valid) {
+    await writeLicense({ ...lic, validatedAt: new Date(now).toISOString() }, fileOverride);
+    return { unlocked: true, plan: lic.plan };
+  }
+  if (result.transient && age < REVALIDATE_AFTER_MS + OFFLINE_GRACE_MS) {
+    return { unlocked: true, plan: lic.plan, grace: true };  // offline grace
+  }
+  return { unlocked: false, reason: result.error };
+}
+
+/**
+ * Download the full premium catalog through the gated endpoint (server-side
+ * key check) and extract it to ~/.vanara/catalog. Requires a stored license.
+ */
+export async function syncPremium({ fetchFn = fetch, fileOverride, dirOverride } = {}) {
+  const lic = await readLicense(fileOverride);
+  if (!lic?.key) return { ok: false, error: 'No license — run: vanara unlock <license-key>' };
+  const base = process.env.VANARA_PREMIUM_URL ?? POLAR.premiumUrl;
+  if (!base) return { ok: false, error: 'Premium delivery not live yet — your license is saved; run `vanara sync` after launch.' };
+
+  const dir = dirOverride ?? PREMIUM_DIR;
+  // Send the key in the Authorization header, not the URL — query strings get
+  // retained in proxy/CDN/Worker request logs; headers generally do not.
+  const res = await fetchFn(base, { headers: { authorization: `Bearer ${lic.key}` } });
+  if (res.status === 402 || res.status === 403) return { ok: false, error: 'License not accepted by the catalog server (expired or cancelled?).' };
+  if (!res.ok) return { ok: false, error: `Catalog server returned ${res.status}.` };
+
+  await mkdir(dir, { recursive: true });
+  const tarball = path.join(dir, '.premium.tgz');
+  await pipeline(Readable.fromWeb(res.body), createWriteStream(tarball));
+  try {
+    // Defense-in-depth: the tarball is our own paid asset behind a license gate,
+    // but never trust downloaded archive contents. Inspect the member list and
+    // refuse absolute paths or `..` traversal (zip-slip) before extracting.
+    assertSafeTar(execFileSync('tar', ['-tzf', '.premium.tgz'], { cwd: dir, encoding: 'utf8' }));
+    // relative path + cwd: GNU tar on Windows misreads "C:" in absolute paths
+    execFileSync('tar', ['-xzf', '.premium.tgz'], { cwd: dir });
+  } finally {
+    await rm(tarball, { force: true });
+  }
+  return { ok: true, dir };
+}