dxai-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 d3v
+
+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/README.md

@@ -0,0 +1,172 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/nandha-kumar-hajari/dxai/main/docs/public/og.png" alt="dxai — make your repo ready for every AI coding agent" width="640">
+</p>
+
+<p align="center">
+  <strong>One command to make your repo ready for every AI coding agent.</strong>
+</p>
+
+`dxai` is an interactive CLI that configures **MCP servers**, **agent skills**, **Cursor rules and commands**, **project instruction files** (`CLAUDE.md`, `GEMINI.md`, `AGENTS.md`), and **AI-friendly project scaffolding** across **Cursor, Claude Code, VS Code / Copilot, OpenAI Codex, Gemini CLI, Google Antigravity, and Devin Desktop (formerly Windsurf)** — simultaneously and in the right format for each.
+
+📚 **Full documentation:** <https://nandha-kumar-hajari.github.io/dxai/>
+
+---
+
+## Quick Start
+
+```bash
+npx dxai-cli            # interactive menu
+npx dxai-cli system     # global IDE configs only
+npx dxai-cli project    # repo-local scaffolding only
+npx dxai-cli --yes      # accept defaults; non-interactive
+npx dxai-cli --help     # full usage
+```
+
+## Headline features
+
+- **One config, every tool.** Pick an MCP server once and dxai writes the right format for every selected agent (JSON for Cursor / VS Code / Gemini / Antigravity / Devin, TOML for Codex, `claude mcp add` for Claude Code). The full per-agent map lives in [Supported Agents](https://nandha-kumar-hajari.github.io/dxai/reference/agents/).
+- **Profiles for teams.** `dxai save-profile --here` writes `./.dxai/profile.json`. Teammates run `dxai apply` to get the same setup.
+- **Drift-aware introspection.** `dxai list` / `status` / `doctor` read a manifest of installs, so cleanup is precise and PR review can spot config drift.
+- **CI-ready.** Set `CI=true` (or pass `--yes`) for unattended runs. JSON output mode pipes into the rest of your tooling.
+- **Backed by the official MCP Registry.** Catalog entries link to their record on [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io); a weekly sync keeps the bundled catalog current and `dxai update` re-resolves live. Any registry server can be added by name: `dxai add io.github.owner/server`.
+- **Bundled + remote registry.** `dxai update` refreshes the MCP / skill catalog from a remote URL; bundled JSON is the offline fallback. Override the source with `DXAI_REGISTRY_URL`. Network calls (registry refresh, skill downloads) use native `fetch` with per-attempt timeouts and retry/backoff — no `curl` dependency.
+- **Reversible.** Every write is backed up as `<file>.bak.<ts>`; `dxai rollback` restores the most recent snapshot (and snapshots the current file first, so it's undoable).
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `dxai system` | Global IDE configs, MCP servers, agent skills |
+| `dxai project` | Repo-local AI scaffolding (rules, CLAUDE.md, AGENTS.md, etc.) |
+| `dxai both` | System + project setup in one go |
+| `dxai init` | Alias for `dxai project` (first-time project setup) |
+| `dxai add <mcp...>` | Add MCP server(s) to detected agents — fast path, no wizard |
+| `dxai remove <mcp...>` (alias `rm`) | Remove MCP server(s) from detected agents |
+| `dxai apply [name]` | Run setup using a saved profile |
+| `dxai save-profile [name]` | Save selections as a reusable profile |
+| `dxai profiles` | List discoverable profiles |
+| `dxai list` | Show what dxai installed (from manifest) |
+| `dxai status` | Compare manifest with live config (drift detection) |
+| `dxai doctor` | Validate dxai installation |
+| `dxai update` | Refresh registry cache from remote |
+| `dxai rollback` | Restore dxai-managed files from their most recent `.bak.<ts>` backup |
+| `dxai cleanup [scope]` (alias `reset`) | Remove dxai-managed configs and files (`system`/`project`/`both`; supports `-y`, `--json`, `--dry-run`, `--backups`) |
+
+Per-command pages with full options tables: [Reference / Commands](https://nandha-kumar-hajari.github.io/dxai/reference/commands/).
+
+## Non-interactive / CI
+
+```bash
+dxai system --yes \
+  --agents cursor,claude-code \
+  --mcp github,playwright,context7
+
+dxai project --yes \
+  --stack react,node \
+  --features cursor-rules,agents-md,editorconfig
+
+CI=true dxai system --agents cursor --dry-run --json | jq .
+```
+
+Full flag table: [Reference / Flags](https://nandha-kumar-hajari.github.io/dxai/reference/flags/).
+
+## Requirements
+
+- **Node.js 18+** — verified in CI on Node 18, 20, 22.
+- **npm** / **npx** (ships with Node).
+- **Git** — recommended.
+
+dxai is verified on **macOS, Linux, and Windows** in the GitHub Actions matrix.
+
+---
+
+## Setup, tests, and CI
+
+```bash
+git clone https://github.com/nandha-kumar-hajari/dxai.git
+cd dxai
+npm install
+npm test                          # 143 tests, ~0.5s (node:test, no extra framework)
+npm run smoke                     # quick --version + --help check
+npm link                          # optional: simulate `npx dxai-cli`
+```
+
+CI matrix runs on every push and PR across **Ubuntu, macOS, Windows × Node 18, 20, 22**:
+
+1. `node --check` for every `.js` in `src/` and `bin/`
+2. `npm test`
+3. Smoke run of `dxai --version` and `dxai --help`
+4. `npm run docs:check` (drift guard — fails if `bin/cli.js` flags or registry JSON change without regenerating docs)
+
+## Documentation site
+
+Built with **Astro + Starlight**. Sources live under `docs/`. Most pages are hand-written; registry tables, CLI reference, schema docs, and the changelog are auto-generated from source code.
+
+```bash
+npm run docs:install              # one-time: install docs deps
+npm run docs:dev                  # dev server at http://localhost:4321
+npm run docs:generate             # run all generators (idempotent)
+npm run docs:build                # generators → astro build → docs/dist/
+npm run docs:check                # drift guard (CI uses this)
+npm run docs:preview              # preview built site
+```
+
+Auto-generated pages (regenerated by the generators in `scripts/docs/`):
+
+| Page | Source |
+|---|---|
+| [Registry / MCP servers](https://nandha-kumar-hajari.github.io/dxai/registry/mcp-servers/) | `src/registry/data/mcp-servers.json` |
+| [Registry / Skills](https://nandha-kumar-hajari.github.io/dxai/registry/skills/) | `src/registry/data/skills.json` |
+| [Registry / Stacks](https://nandha-kumar-hajari.github.io/dxai/registry/stacks/) | `src/registry/stacks.js` (`TECH_STACKS`, `CURSOR_RULES`) |
+| [Registry / Cursor commands](https://nandha-kumar-hajari.github.io/dxai/registry/cursor-commands/) | `src/registry/stacks.js` (`CURSOR_COMMANDS`) |
+| [Reference / Commands](https://nandha-kumar-hajari.github.io/dxai/reference/commands/) | `bin/cli.js` (`buildProgram()`) |
+| [Reference / Flags](https://nandha-kumar-hajari.github.io/dxai/reference/flags/) | `bin/cli.js` (`buildProgram()`) |
+| [Reference / Profile schema](https://nandha-kumar-hajari.github.io/dxai/reference/profile-schema/) | `src/profile.js` (`PROFILE_KEYS`) |
+| [Reference / Manifest schema](https://nandha-kumar-hajari.github.io/dxai/reference/manifest-schema/) | `src/manifest.js` (`emptyManifest`) |
+| [Changelog](https://nandha-kumar-hajari.github.io/dxai/changelog/) | `git log` (conventional commits) |
+
+The site also publishes `llms.txt` / `llms-full.txt` for AI-agent consumption (via `starlight-llms-txt`).
+
+## Project structure
+
+```
+bin/cli.js                          # commander entry, exports buildProgram()
+src/
+  index.js                          # run / apply / saveProfileCmd / listProfilesCmd
+  runtime.js                        # option normalization
+  profile.js                        # profile load / merge / save / discovery
+  manifest.js                       # manifest read / write / record helpers
+  inspect.js                        # list / status / doctor
+  update.js                         # update (remote registry refresh)
+  auto-update.js                    # periodic TTL-based catalog refresh
+  cleanup.js                        # cleanup / reset (manifest-aware)
+  rollback.js                       # restore files from .bak.<ts> snapshots
+  mcp-cmd.js                        # fast-path add / remove MCP commands
+  config-writer.js                  # file writers + dry-run previews
+  config-remover.js                 # scan + remove helpers
+  net.js                            # fetch with timeout + retry/backoff
+  fs-atomic.js                      # atomic writes (temp + rename)
+  detect.js                         # OS, prerequisite, agent detection
+  detect-project.js                 # stack / tooling / git inference
+  branding.js                       # banner / colors / message helpers
+  registry/
+    mcp-servers.js                  # re-exports loaded via loader
+    skills.js                       # re-exports loaded via loader
+    stacks.js                       # tech stacks, Cursor rules, commands, templates
+    loader.js                       # cache > bundled JSON resolution; remote fetch
+    data/{mcp-servers,skills}.json  # bundled catalogs
+
+test/                               # node:test suite (143 tests)
+docs/                               # Astro + Starlight site
+scripts/docs/                       # doc generators (gen-*.mjs + lib/render.mjs)
+.github/workflows/                  # ci.yml + docs.yml
+ROADMAP.md                          # tracked gaps and future work
+```
+
+## Roadmap
+
+See [ROADMAP.md](./ROADMAP.md). The Top 5 focus areas — bug fixes, non-interactive mode, profiles, manifest + introspection, remote registry + tests — are complete. Documentation site (this section) shipped on top of that.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+
+import { Command, Option } from 'commander';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { run, apply, saveProfileCmd, listProfilesCmd } from '../src/index.js';
+import { cleanup } from '../src/cleanup.js';
+import { addMcp, removeMcp } from '../src/mcp-cmd.js';
+import { rollbackCmd } from '../src/rollback.js';
+import { listCmd, statusCmd, doctorCmd } from '../src/inspect.js';
+import { updateCmd } from '../src/update.js';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+
+// Comma-separated list parser for repeatable selection flags.
+const csv = (v) => v.split(',').map((s) => s.trim()).filter(Boolean);
+
+// Build the configured commander program. Exported so doc generators (and any
+// other tooling) can introspect subcommands and options as data.
+export function buildProgram() {
+  const program = new Command();
+
+  program
+    .name('dxai')
+    .description('Interactive CLI to bootstrap your AI-powered dev environment.')
+    .version(pkg.version, '-v, --version', 'output the version number')
+    .showHelpAfterError('(run with --help for usage)');
+
+  // Shared options applied to setup subcommands.
+  const sharedSetupOptions = (cmd) =>
+    cmd
+      .addOption(new Option('-y, --yes', 'skip prompts; use defaults / values from flags'))
+      .addOption(new Option('--agents <list>', 'comma-separated agent IDs (cursor,claude-code,vscode,vscode-insiders,codex,gemini,antigravity,antigravity-ide,antigravity-cli,devin-desktop,devin-cli; former ids like windsurf still work)').argParser(csv))
+      .addOption(new Option('--mcp <list>', 'comma-separated MCP server IDs').argParser(csv))
+      .addOption(new Option('--skills <list>', 'comma-separated skill IDs').argParser(csv))
+      .addOption(new Option('--tools <list>', 'comma-separated automation tool IDs (agent-browser,agent-device)').argParser(csv))
+      .addOption(new Option('--features <list>', 'comma-separated project feature IDs').argParser(csv))
+      .addOption(new Option('--stack <list>', 'comma-separated tech stack IDs').argParser(csv))
+      .addOption(new Option('--profile <nameOrPath>', 'load a saved profile (name or path)'))
+      .addOption(new Option('--no-profile', 'skip auto-discovery of project/user profiles'))
+      .addOption(new Option('--json', 'emit machine-readable JSON output (no colors, no spinners)'))
+      .addOption(new Option('--dry-run', 'preview changes without writing'))
+      .addOption(new Option('--no-update', 'skip the periodic catalog refresh check'));
+
+  sharedSetupOptions(
+    program
+      .command('system')
+      .description('System-level setup (global IDE configs, MCP servers, skills)')
+      .action(async (opts) => {
+        await run('system', opts);
+      })
+  );
+
+  sharedSetupOptions(
+    program
+      .command('project')
+      .alias('init')
+      .description('Project-level setup (stack, rules, CLAUDE.md, .editorconfig, etc.)')
+      .action(async (opts) => {
+        await run('project', opts);
+      })
+  );
+
+  sharedSetupOptions(
+    program
+      .command('both')
+      .description('Run system + project setup in one go')
+      .action(async (opts) => {
+        await run('both', opts);
+      })
+  );
+
+  program
+    .command('cleanup [scope]')
+    .alias('reset')
+    .description('Remove dxai-managed configs, files, and skills (scope: system | project | both)')
+    .addOption(new Option('-y, --yes', 'non-interactive; remove everything dxai-managed (custom-edit-prone files and backups are kept)'))
+    .addOption(new Option('--backups', 'with --yes/--json: also delete .bak.<ts> backup files'))
+    .addOption(new Option('--json', 'emit machine-readable JSON output (implies non-interactive)'))
+    .addOption(new Option('--dry-run', 'preview what would be removed without deleting anything'))
+    .action(async (scope, opts) => {
+      await cleanup(scope, opts);
+    });
+
+  // dxai add <id...> — fast path: add MCP server(s) without the wizard
+  program
+    .command('add <mcp...>')
+    .description('Add MCP server(s) to detected agents (fast path, no wizard). Takes catalogue ids or official MCP Registry names like io.github.owner/server')
+    .addOption(new Option('--agents <list>', 'comma-separated agent IDs to target (default: detected)').argParser(csv))
+    .addOption(new Option('--project', 'write to project-level config instead of global'))
+    .addOption(new Option('-y, --yes', 'non-interactive; use defaults for any required inputs'))
+    .addOption(new Option('--json', 'emit machine-readable JSON output'))
+    .addOption(new Option('--dry-run', 'preview what would be added without writing'))
+    .action(async (mcp, opts) => {
+      await addMcp(mcp, opts);
+    });
+
+  // dxai remove <id...> — fast path: remove MCP server(s) without the wizard
+  program
+    .command('remove <mcp...>')
+    .alias('rm')
+    .description('Remove MCP server(s) from detected agents (fast path, no wizard)')
+    .addOption(new Option('--agents <list>', 'comma-separated agent IDs to target (default: detected)').argParser(csv))
+    .addOption(new Option('--project', 'remove from project-level config instead of global'))
+    .addOption(new Option('--json', 'emit machine-readable JSON output'))
+    .addOption(new Option('--dry-run', 'preview what would be removed without writing'))
+    .action(async (mcp, opts) => {
+      await removeMcp(mcp, opts);
+    });
+
+  // dxai rollback — restore config/project files from their latest .bak.<ts>
+  program
+    .command('rollback')
+    .description('Restore dxai-managed files from their most recent .bak.<ts> backup')
+    .addOption(new Option('--list', 'list restorable backups without changing anything'))
+    .addOption(new Option('-y, --yes', 'restore the latest backup for every file without prompting'))
+    .addOption(new Option('--json', 'emit machine-readable JSON output'))
+    .addOption(new Option('--dry-run', 'preview what would be restored without writing'))
+    .action(async (opts) => {
+      await rollbackCmd(opts);
+    });
+
+  // dxai apply [name|path] — non-interactive run from a saved profile
+  program
+    .command('apply [nameOrPath]')
+    .description('Run setup using a saved profile (auto-loads ./.dxai/profile.json if no name given)')
+    .addOption(new Option('--json', 'emit machine-readable JSON output'))
+    .addOption(new Option('--dry-run', 'preview changes without writing'))
+    .action(async (nameOrPath, opts) => {
+      await apply(nameOrPath, opts);
+    });
+
+  // dxai save-profile <name> — capture flag values into a profile file
+  program
+    .command('save-profile [name]')
+    .description('Save selections as a profile. Defaults to ~/.dxai/profiles/<name>.json')
+    .addOption(new Option('--mode <mode>', 'mode to record: system | project | both'))
+    .addOption(new Option('--agents <list>', 'comma-separated agent IDs').argParser(csv))
+    .addOption(new Option('--mcp <list>', 'comma-separated MCP server IDs').argParser(csv))
+    .addOption(new Option('--skills <list>', 'comma-separated skill IDs').argParser(csv))
+    .addOption(new Option('--features <list>', 'comma-separated feature IDs').argParser(csv))
+    .addOption(new Option('--stack <list>', 'comma-separated stack IDs').argParser(csv))
+    .addOption(new Option('--here', 'save as project-local ./.dxai/profile.json instead'))
+    .addOption(new Option('--path <path>', 'save to an explicit file path'))
+    .addOption(new Option('--json', 'emit machine-readable JSON output'))
+    .action(async (name, opts) => {
+      await saveProfileCmd(name, opts);
+    });
+
+  // dxai profiles — list discoverable profiles
+  program
+    .command('profiles')
+    .description('List discoverable profiles (~/.dxai/profiles + ./.dxai)')
+    .addOption(new Option('--json', 'emit machine-readable JSON output'))
+    .action(async (opts) => {
+      await listProfilesCmd(opts);
+    });
+
+  // dxai list — show what dxai installed (from manifest)
+  program
+    .command('list')
+    .description('Show dxai-managed installs from the manifest (system + project)')
+    .addOption(new Option('--json', 'emit machine-readable JSON output'))
+    .action(async (opts) => {
+      await listCmd(opts);
+    });
+
+  // dxai status — diff manifest vs actual config files
+  program
+    .command('status')
+    .description('Compare manifest with live config files; surface drift')
+    .addOption(new Option('--json', 'emit machine-readable JSON output'))
+    .action(async (opts) => {
+      await statusCmd(opts);
+    });
+
+  // dxai doctor — validate environment + configs
+  program
+    .command('doctor')
+    .description('Validate dxai installation: configs parse, env vars set, tools on PATH')
+    .addOption(new Option('--json', 'emit machine-readable JSON output'))
+    .addOption(new Option('--handshake', 'spawn each installed MCP server and verify it speaks JSON-RPC over stdio'))
+    .action(async (opts) => {
+      await doctorCmd(opts);
+    });
+
+  // dxai update — refresh registry cache (MCP servers, skills) from remote
+  program
+    .command('update')
+    .description('Fetch the latest registry (MCP servers, skills) and cache it locally')
+    .addOption(new Option('--json', 'emit machine-readable JSON output'))
+    .addOption(new Option('--registry-version <ref>', 'registry tag/branch to fetch (default: main)'))
+    .addOption(new Option('--registry-url <url>', 'registry base URL (overrides DXAI_REGISTRY_URL)'))
+    .addOption(new Option('--no-resolve', 'skip re-resolving registry-linked MCP servers live from the official MCP Registry'))
+    .action(async (opts) => {
+      await updateCmd(opts);
+    });
+
+  // Default action when no subcommand is given — preserve interactive menu.
+  sharedSetupOptions(
+    program
+      .command('start', { isDefault: true, hidden: true })
+      .description('Interactive menu (default when no subcommand is given)')
+      .action(async (opts) => {
+        await run(undefined, opts);
+      })
+  );
+
+  // Examples block.
+  program.addHelpText(
+    'after',
+    `
+Examples:
+  $ dxai                                      # interactive menu
+  $ dxai system                               # interactive system setup
+  $ dxai project --yes                        # accept defaults, no prompts
+  $ dxai system -y --agents cursor,claude-code --mcp github,playwright
+  $ dxai project -y --stack react,node --features cursor-rules,agents-md
+  $ CI=true dxai system --agents cursor       # non-interactive (CI mode)
+  $ dxai save-profile myteam --agents cursor --mcp github,playwright
+  $ dxai add github playwright                # add MCP servers to detected agents
+  $ dxai add context7 --agents cursor,codex   # target specific agents
+  $ dxai add io.github.upstash/context7       # any server from the official MCP Registry
+  $ dxai remove github --dry-run              # preview an MCP removal
+  $ dxai apply myteam                         # run setup from a saved profile
+  $ dxai apply --dry-run                      # auto-load ./.dxai/profile.json
+  $ dxai profiles                             # list saved profiles
+  $ dxai cleanup                              # remove dxai-managed configs
+  $ dxai rollback --list                      # show restorable .bak backups
+  $ dxai rollback --dry-run                   # preview a restore, write nothing
+
+Profiles are auto-loaded from (in order):
+  ./.dxai/profile.json   (project-local)
+  ~/.dxai/config.json    (user-level)
+  ~/.dxairc(.json)
+Pass --no-profile to skip auto-discovery, or --profile <nameOrPath> to override.
+
+Environment:
+  CI=true                  Force non-interactive output (plain text, no spinners)
+  NO_COLOR=1               Disable colored output
+  DXAI_DRY_RUN=1           Equivalent to --dry-run
+  DXAI_NO_AUTO_UPDATE=1    Disable the periodic catalog refresh (same as --no-update)
+  DXAI_UPDATE_TTL_DAYS=N   Days between catalog refresh checks (default 7)
+  DXAI_UPDATE_TIMEOUT_MS=N Network timeout for the background refresh (default 4000)
+  DXAI_REGISTRY_URL=<url>  Override the registry base URL (host a fork)
+  DXAI_MCP_REGISTRY_URL=<url>  Override the official MCP Registry base URL
+`
+  );
+
+  return program;
+}
+
+// Only parse argv when invoked as the entry script (not when imported).
+const invokedDirectly = (() => {
+  try {
+    if (!process.argv[1]) return false;
+    const selfPath = realpathSync(fileURLToPath(import.meta.url));
+    const argvPath = realpathSync(process.argv[1]);
+    return selfPath === argvPath;
+  } catch {
+    return false;
+  }
+})();
+
+if (invokedDirectly) {
+  buildProgram().parseAsync(process.argv).catch((err) => {
+    console.error(err.stack || err.message || err);
+    process.exit(1);
+  });
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "dxai-cli",
+  "version": "1.0.0",
+  "description": "Interactive CLI to bootstrap your AI-powered dev environment — MCP servers, agent skills, cursor rules & more across Cursor, Claude Code, VS Code / Copilot, Codex, Gemini CLI, Windsurf, and Antigravity.",
+  "keywords": [
+    "ai",
+    "cursor",
+    "claude-code",
+    "codex",
+    "gemini-cli",
+    "mcp",
+    "agent-skills",
+    "developer-tools",
+    "setup",
+    "cli"
+  ],
+  "author": "d3v",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nandha-kumar-hajari/dxai.git"
+  },
+  "homepage": "https://github.com/nandha-kumar-hajari/dxai#readme",
+  "bugs": {
+    "url": "https://github.com/nandha-kumar-hajari/dxai/issues"
+  },
+  "type": "module",
+  "bin": {
+    "dxai": "bin/cli.js"
+  },
+  "main": "src/index.js",
+  "scripts": {
+    "test": "node scripts/run-tests.mjs",
+    "lint": "eslint .",
+    "smoke": "node bin/cli.js --version && node bin/cli.js --help > /dev/null",
+    "docs:install": "npm --prefix docs install",
+    "docs:dev": "npm --prefix docs run dev",
+    "docs:build": "npm run docs:generate && npm --prefix docs run build",
+    "docs:preview": "npm --prefix docs run preview",
+    "docs:generate": "node scripts/docs/generate-all.mjs",
+    "docs:check": "node scripts/docs/check-drift.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^14.0.3",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^9.2.23",
+    "ora": "^8.0.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.7.0",
+    "globals": "^17.7.0"
+  }
+}

package/src/auto-update.js

@@ -0,0 +1,106 @@
+// Periodic, opt-out catalog auto-refresh.
+//
+// The catalog (MCP servers, skills, automation tools) is decoupled from CLI releases:
+// `dxai update` fetches it from the remote and caches it under ~/.dxai/cache/. This module
+// makes that refresh happen on its own, on a TTL, so catalog improvements reach users who
+// never run `dxai update` manually.
+//
+// IMPORTANT: the registry modules load their data at import time, so a refresh during a run
+// updates the on-disk cache for the *next* run — it does not hot-swap the in-memory catalog.
+// We refresh the cache and (optionally) nudge; we never pretend it changed the current run.
+
+import fs from 'fs-extra';
+import path from 'path';
+import { CACHE_DIR, registryBaseFor } from './registry/loader.js';
+import { refreshRegistry } from './update.js';
+import { infoMsg } from './branding.js';
+import { writeJsonAtomic } from './fs-atomic.js';
+
+const LAST_CHECK_PATH = path.join(CACHE_DIR, '.last-check.json');
+const DEFAULT_TTL_DAYS = 7;
+const DEFAULT_TIMEOUT_MS = 4000;
+
+export function ttlMs(env = process.env) {
+  const days = Number(env.DXAI_UPDATE_TTL_DAYS) || DEFAULT_TTL_DAYS;
+  return days * 24 * 60 * 60 * 1000;
+}
+
+function timeoutMs(env = process.env) {
+  return Number(env.DXAI_UPDATE_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS;
+}
+
+// Due for a refresh when we have never recorded a check, or the last one is older than the TTL.
+export function isDue(lastCheck, now, ttl) {
+  if (!lastCheck || !lastCheck.checkedAt) return true;
+  const last = Date.parse(lastCheck.checkedAt);
+  if (Number.isNaN(last)) return true;
+  return now - last > ttl;
+}
+
+// Suppress the check for machine output, CI, explicit opt-out, or --no-update.
+export function shouldSkip(runtime = {}, env = process.env) {
+  return !!(runtime.json || runtime.ci || env.DXAI_NO_AUTO_UPDATE || runtime.update === false);
+}
+
+export function readLastCheck(file = LAST_CHECK_PATH) {
+  if (!fs.existsSync(file)) return null;
+  try {
+    return fs.readJsonSync(file);
+  } catch {
+    return null;
+  }
+}
+
+export function recordCheck(now, file = LAST_CHECK_PATH) {
+  // Best-effort: an unwritable cache dir must not propagate out of the
+  // background refresh and abort the user's setup.
+  try {
+    writeJsonAtomic(file, { checkedAt: new Date(now).toISOString() }, { spaces: 2 });
+  } catch { /* ignore — we'll just re-check next run */ }
+}
+
+// Orchestrator. Dependencies are injectable so the whole flow is testable without a network.
+export async function maybeRefreshCatalog(runtime = {}, deps = {}) {
+  const {
+    now = Date.now(),
+    env = process.env,
+    refresh = refreshRegistry,
+    lastCheckPath = LAST_CHECK_PATH,
+    log = infoMsg,
+  } = deps;
+
+  if (shouldSkip(runtime, env)) return { skipped: true };
+
+  const record = readLastCheck(lastCheckPath);
+  if (!isDue(record, now, ttlMs(env))) return { due: false };
+
+  // Record immediately so an offline failure doesn't retry every single run.
+  recordCheck(now, lastCheckPath);
+
+  // First ever check: just baseline the timer. The freshly-installed package already
+  // bundles a recent snapshot, so there's no need to hit the network on the very first run.
+  if (!record) return { firstRun: true };
+
+  try {
+    // Background check: fail fast. Retrying an offline host would stall the
+    // user's run for seconds; the interactive `dxai update` still gets retries.
+    // One request per file, no live re-resolution: the bot-maintained snapshot
+    // is what a background refresh picks up.
+    const results = await refresh({ base: registryBaseFor({}), timeoutMs: timeoutMs(env), retries: 0, resolve: false });
+    // refreshRegistry captures per-file failures rather than throwing; if every file
+    // failed (offline / registry down) treat the whole refresh as a miss.
+    if (results.length && results.every((r) => !r.ok)) {
+      if (!runtime.json) log('Couldn’t refresh catalog (offline?) — using cached data.');
+      return { refreshed: false, results };
+    }
+    const added = results.reduce((n, r) => n + (r.added?.length || 0), 0);
+    const removed = results.reduce((n, r) => n + (r.removed?.length || 0), 0);
+    if ((added || removed) && !runtime.json) {
+      log(`Catalog refreshed — ${added} new / ${removed} removed (applies on your next run).`);
+    }
+    return { refreshed: true, results, added, removed };
+  } catch (err) {
+    if (!runtime.json) log('Couldn’t refresh catalog (offline?) — using cached data.');
+    return { refreshed: false, error: err.message };
+  }
+}