@gitpagedocs/cli 1.1.59 → 1.1.61

package/README.md

@@ -28,7 +28,7 @@ npx @gitpagedocs/cli
 | `gitpagedocs deploy` / `pages [actions\|deploy]` | Configure GitHub Pages via Actions + push |
 | `gitpagedocs docs` | Refresh managed regions of README/CONTRIBUTING/SECURITY |
 | `gitpagedocs config clear` | Delete the stored `.gitpagedocsconfig` (wipes saved AI credentials) |
-| `gitpagedocs doctor` · `version` · `update` | Diagnostics / version / update hint |
+| `gitpagedocs doctor` · `version` · `update` | Diagnostics / version / registry update check |
 | `gitpagedocs mcp start` | Start the MCP server over stdio |
 
 The AI-CLI implementation lives in `cli/ai/` (relocated from the frontend so the published package is self-contained).
@@ -114,7 +114,7 @@ Generated artifacts include:
 Example:
 
 ```bash
-npx gitpagedocs --owner vidigal-code --repo energy-bill-ai-parser --path git-docs --push
+npx @gitpagedocs/cli --owner vidigal-code --repo energy-bill-ai-parser --path git-docs --push
 ```
 
 Expected URL after deployment:
@@ -128,7 +128,7 @@ https://vidigal-code.github.io/energy-bill-ai-parser/git-docs/
 The CLI now includes a dedicated interactive AI mode:
 
 ```bash
-npx gitpagedocs ai
+npx @gitpagedocs/cli ai
 ```
 
 ### What it does
@@ -162,7 +162,7 @@ permissions on POSIX systems:
 Set `GITPAGEDOCS_CONFIG_DIR` to override the directory; delete the stored file
 and its credentials with `gitpagedocs config clear`; a legacy
 `.gitpagedocsconfig` in the repository root is migrated automatically on the next
-run. You can create/edit this file manually and then run `npx gitpagedocs ai`:
+run. You can create/edit this file manually and then run `npx @gitpagedocs/cli ai`:
 
 ```json
 {

package/content/docs-en.mjs

@@ -46,11 +46,11 @@ This guide configures your repository from zero to running docs.
 ## Install and generate
 
 1. Install package:
-   - \`npm install gitpagedocs\`
+   - \`npm install @gitpagedocs/cli\`
 2. Generate docs config and versions:
-   - \`npx gitpagedocs\`
+   - \`npx @gitpagedocs/cli\`
 3. Optional: generate local layouts/templates:
-   - \`npx gitpagedocs --layoutconfig\`
+   - \`npx @gitpagedocs/cli --layoutconfig\`
 
 ## Local run
 
@@ -62,7 +62,7 @@ This guide configures your repository from zero to running docs.
 
 ## CLI behavior
 
-\`npx gitpagedocs\` generates only artifacts in \`gitpagedocs/\`:
+\`npx @gitpagedocs/cli\` generates only artifacts in \`gitpagedocs/\`:
 
 - JSON + markdown docs assets
 - No \`index.html\`
@@ -85,7 +85,7 @@ Git Page Docs is a **pnpm + turborepo monorepo** that turns a repository's \`git
 ## Monorepo packages
 
 - **frontend/** — Next.js 15 (App Router, React 19) documentation viewer, static-exported for GitHub Pages.
-- **cli/** — the published \`gitpagedocs\` npm package (\`npm install -g gitpagedocs\`): scaffolds the docs contract, generates docs with AI, configures Pages, and runs the MCP server.
+- **cli/** — the published \`@gitpagedocs/cli\` npm package (\`npm install -g @gitpagedocs/cli\`): scaffolds the docs contract, generates docs with AI, configures Pages, and runs the MCP server.
 - **tools/** — \`@gitpagedocs/tools\`, the shared business-logic core: the 14-provider AI system, the encrypted credential vault, the config loader, caches, and the logger.
 - **mcp/** — \`@gitpagedocs/mcp\`, a Model Context Protocol server (20 tools + 7 resources).
 - **gitpagedocs/** — the user contract: \`config.json\`, versioned docs, and layouts.
@@ -122,10 +122,10 @@ Complete reference of CLI options, configuration keys, and runtime features.
 | \`gitpagedocs document[:repo\\|:file\\|:folder]\` | Generate documentation with AI |
 | \`gitpagedocs deploy\` / \`pages [actions\\|deploy]\` | Configure GitHub Pages via Actions + push |
 | \`gitpagedocs docs\` | Refresh README/CONTRIBUTING/SECURITY managed regions |
-| \`gitpagedocs doctor\` / \`version\` / \`update\` | Diagnostics / version / update hint |
+| \`gitpagedocs doctor\` / \`version\` / \`update\` | Diagnostics / version / registry update check |
 | \`gitpagedocs mcp start\` | Start the MCP server over stdio |
 
-Install globally with \`npm install -g gitpagedocs\`, or run one-off with \`npx gitpagedocs\`.
+Install globally with \`npm install -g @gitpagedocs/cli\`, or run one-off with \`npx @gitpagedocs/cli\`.
 
 ## CLI options
 
@@ -419,8 +419,8 @@ Provide owner + repository to load docs from repositories that contain \`gitpage
 ## Self-hosted GitHub Pages
 
 1. Generate docs:
-   - \`npx gitpagedocs\`
-   - or \`npx gitpagedocs --layoutconfig\` for local templates
+   - \`npx @gitpagedocs/cli\`
+   - or \`npx @gitpagedocs/cli --layoutconfig\` for local templates
 2. Set \`site.rendering\` in \`gitpagedocs/config.json\`:
    - \`https://<your-user>.github.io/<your-repo>/\`
 3. Build and validate:
@@ -485,8 +485,8 @@ Themes are JSON templates mapped by \`layoutsConfig.json\`.
 
 ## Strategy options
 
-- Default mode (\`npx gitpagedocs\`): use official layouts/templates from the upstream repository.
-- Local mode (\`npx gitpagedocs --layoutconfig\`): generate and use local templates from your repository.
+- Default mode (\`npx @gitpagedocs/cli\`): use official layouts/templates from the upstream repository.
+- Local mode (\`npx @gitpagedocs/cli --layoutconfig\`): generate and use local templates from your repository.
 
 ## Local layout files
 

package/content/docs-es.mjs

@@ -55,7 +55,7 @@ Esta guia lleva el proyecto desde cero hasta docs corriendo.
 
 ## Comportamiento de la CLI
 
-\`npx gitpagedocs\` (o \`npm run gitpagedocs\`) genera artefactos en la carpeta oficial \`gitpagedocs/\`.
+\`npx @gitpagedocs/cli\` (o \`npm run gitpagedocs\`) genera artefactos en la carpeta oficial \`gitpagedocs/\`.
 
 - Genera solo markdown/json
 - No genera \`index.html\`
@@ -78,7 +78,7 @@ Git Page Docs es un monorepo pnpm + turborepo que convierte la carpeta \`gitpage
 ## Paquetes del monorepo
 
 - **frontend/** — visor Next.js 15 (App Router, React 19), exportado estaticamente para GitHub Pages.
-- **cli/** — el paquete npm publicado \`gitpagedocs\` (\`npm install -g gitpagedocs\`): genera la estructura de docs, documenta con IA, configura Pages y ejecuta el servidor MCP.
+- **cli/** — el paquete npm publicado \`@gitpagedocs/cli\` (\`npm install -g @gitpagedocs/cli\`): genera la estructura de docs, documenta con IA, configura Pages y ejecuta el servidor MCP.
 - **tools/** — \`@gitpagedocs/tools\`, el nucleo de logica compartido: sistema de IA con 14 proveedores, boveda de credenciales cifrada, cargador de config, caches y logger.
 - **mcp/** — \`@gitpagedocs/mcp\`, servidor Model Context Protocol (20 herramientas + 7 recursos).
 - **gitpagedocs/** — el contrato del usuario: \`config.json\`, docs versionados y layouts.
@@ -105,11 +105,11 @@ Referencia completa de opciones CLI, claves de configuracion y funciones del run
 
 | Comando | Descripcion |
 |---------|-------------|
-| \`npx gitpagedocs\` | Genera config y docs en \`gitpagedocs/\` |
-| \`npx gitpagedocs --layoutconfig\` | Tambien genera layouts/templates locales |
-| \`npx gitpagedocs --home\` | Distribucion standalone (\`gitpagedocshome/\`) |
-| \`npx gitpagedocs --push --owner X --repo Y\` | Configura workflow, commit, push |
-| \`npx gitpagedocs --interactive\` / \`-i\` | Modo interactivo con prompts |
+| \`npx @gitpagedocs/cli\` | Genera config y docs en \`gitpagedocs/\` |
+| \`npx @gitpagedocs/cli --layoutconfig\` | Tambien genera layouts/templates locales |
+| \`npx @gitpagedocs/cli --home\` | Distribucion standalone (\`gitpagedocshome/\`) |
+| \`npx @gitpagedocs/cli --push --owner X --repo Y\` | Configura workflow, commit, push |
+| \`npx @gitpagedocs/cli --interactive\` / \`-i\` | Modo interactivo con prompts |
 
 ## Opciones CLI
 

package/content/docs-pt.mjs

@@ -55,7 +55,7 @@ Este guia leva o projeto do zero ate docs rodando.
 
 ## Comportamento da CLI
 
-\`npx gitpagedocs\` (ou \`npm run gitpagedocs\`) gera os artefatos na pasta oficial \`gitpagedocs/\`.
+\`npx @gitpagedocs/cli\` (ou \`npm run gitpagedocs\`) gera os artefatos na pasta oficial \`gitpagedocs/\`.
 
 - Gera somente markdown/json
 - Nao gera \`index.html\`
@@ -78,7 +78,7 @@ Git Page Docs e um monorepo pnpm + turborepo que transforma a pasta \`gitpagedoc
 ## Pacotes do monorepo
 
 - **frontend/** — visualizador Next.js 15 (App Router, React 19), exportado estaticamente para o GitHub Pages.
-- **cli/** — o pacote npm publicado \`gitpagedocs\` (\`npm install -g gitpagedocs\`): gera a estrutura de docs, documenta com IA, configura o Pages e roda o servidor MCP.
+- **cli/** — o pacote npm publicado \`@gitpagedocs/cli\` (\`npm install -g @gitpagedocs/cli\`): gera a estrutura de docs, documenta com IA, configura o Pages e roda o servidor MCP.
 - **tools/** — \`@gitpagedocs/tools\`, o nucleo de logica compartilhado: sistema de IA com 14 provedores, cofre de credenciais criptografado, loader de config, caches e logger.
 - **mcp/** — \`@gitpagedocs/mcp\`, servidor Model Context Protocol (20 ferramentas + 7 recursos).
 - **gitpagedocs/** — o contrato do usuario: \`config.json\`, docs versionados e layouts.
@@ -105,11 +105,11 @@ Referencia completa de opcoes da CLI, chaves de configuracao e recursos do runti
 
 | Comando | Descricao |
 |---------|------------|
-| \`npx gitpagedocs\` | Gera config e docs em \`gitpagedocs/\` |
-| \`npx gitpagedocs --layoutconfig\` | Tambem gera layouts/templates locais |
-| \`npx gitpagedocs --home\` | Distribuicao standalone (\`gitpagedocshome/\`) |
-| \`npx gitpagedocs --push --owner X --repo Y\` | Configura workflow, commit, push |
-| \`npx gitpagedocs --interactive\` / \`-i\` | Modo interativo com prompts |
+| \`npx @gitpagedocs/cli\` | Gera config e docs em \`gitpagedocs/\` |
+| \`npx @gitpagedocs/cli --layoutconfig\` | Tambem gera layouts/templates locais |
+| \`npx @gitpagedocs/cli --home\` | Distribuicao standalone (\`gitpagedocshome/\`) |
+| \`npx @gitpagedocs/cli --push --owner X --repo Y\` | Configura workflow, commit, push |
+| \`npx @gitpagedocs/cli --interactive\` / \`-i\` | Modo interativo com prompts |
 
 ## Opcoes da CLI
 

package/contracts/doc-versions.mjs

@@ -1,3 +1,3 @@
-export const PACKAGE_VERSION = "1.1.59";
+export const PACKAGE_VERSION = "1.1.61";
 
 export const DOC_VERSIONS = [PACKAGE_VERSION];

package/index.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import path from "node:path";
 import { fileURLToPath } from "node:url";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitpagedocs/cli",
-  "version": "1.1.59",
+  "version": "1.1.61",
   "description": "CLI that scaffolds and maintains gitpagedocs documentation, generates docs with AI, configures GitHub Pages, and runs the MCP server.",
   "bin": {
     "gitpagedocs": "index.mjs"
@@ -29,8 +29,8 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.5.1",
-    "@gitpagedocs/mcp": "^1.1.59",
-    "@gitpagedocs/tools": "^1.1.59",
+    "@gitpagedocs/mcp": "^1.1.61",
+    "@gitpagedocs/tools": "^1.1.61",
     "tsx": "^4.21.0"
   },
   "repository": {

package/presentation/commands/diagnostics.ts

@@ -57,14 +57,108 @@ export async function runDoctor(ctx: CommandContext): Promise<void> {
   console.log(`\n  ${failed === 0 ? "All required checks passed." : `${failed} check(s) need attention.`}\n`);
 }
 
+/** Used only when package.json is unreadable — the CLI's published name. */
+const FALLBACK_PACKAGE = "@gitpagedocs/cli";
+/** The bin this package installs; shown alongside the package name. */
+const BIN_NAME = "gitpagedocs";
+
+interface PackageIdentity {
+  name: string;
+  version: string;
+}
+
+/**
+ * Read the identity from the installed package.json rather than hardcoding it,
+ * so the hint always names the package the user actually has. A hardcoded name
+ * is how `update` ended up advertising an unpublished package.
+ */
+function readPackageIdentity(pkgRoot: string): PackageIdentity {
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(pkgRoot, "package.json"), "utf8"));
+    const name = typeof pkg.name === "string" && pkg.name.length > 0 ? pkg.name : FALLBACK_PACKAGE;
+    return { name, version: String(pkg.version ?? "unknown") };
+  } catch {
+    return { name: FALLBACK_PACKAGE, version: "unknown" };
+  }
+}
+
+type RegistryLookup =
+  | { status: "ok"; latest: string }
+  | { status: "missing" }
+  | { status: "unreachable" };
+
+function registryBase(): string {
+  const configured = process.env.npm_config_registry || "https://registry.npmjs.org";
+  return configured.endsWith("/") ? configured.slice(0, -1) : configured;
+}
+
+/** Resolve the dist-tag `latest` for a package. Never throws. */
+async function fetchLatest(name: string, timeoutMs = 6000): Promise<RegistryLookup> {
+  const encoded = name.split("/").map(encodeURIComponent).join("/");
+  try {
+    const response = await fetch(`${registryBase()}/${encoded}/latest`, {
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (response.status === 404) return { status: "missing" };
+    if (!response.ok) return { status: "unreachable" };
+    const body = (await response.json()) as { version?: unknown };
+    if (typeof body.version === "string" && body.version.length > 0) {
+      return { status: "ok", latest: body.version };
+    }
+    return { status: "unreachable" };
+  } catch {
+    return { status: "unreachable" };
+  }
+}
+
+/** Numeric version compare, prerelease suffix ignored. */
+function compareVersions(a: string, b: string): number {
+  const parts = (value: string): number[] =>
+    value.split("-")[0].split(".").map((piece) => Number.parseInt(piece, 10) || 0);
+  const left = parts(a);
+  const right = parts(b);
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0);
+    if (diff !== 0) return diff < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
 export async function runUpdate(ctx: CommandContext): Promise<void> {
-  const current = readVersion(ctx.pkgRoot);
+  const { name, version } = readPackageIdentity(ctx.pkgRoot);
+  const lookup = await fetchLatest(name);
+  const label = name === BIN_NAME ? `${BIN_NAME} ${version}` : `${BIN_NAME} ${version}  (${name})`;
+  const lines = ["", `  Installed: ${label}`];
+
+  if (lookup.status === "ok") {
+    lines.push(`  Latest:    ${lookup.latest}`);
+  } else if (lookup.status === "missing") {
+    lines.push(`  Latest:    unavailable — the registry has no published ${name}`);
+  } else {
+    lines.push("  Latest:    unknown — could not reach the npm registry");
+  }
+
+  if (lookup.status === "missing") {
+    lines.push(
+      "",
+      "  Nothing can be installed under that name. If the package was renamed",
+      "  or unpublished, check the current one:",
+      "    https://www.npmjs.com/package/@gitpagedocs/cli",
+    );
+  } else if (lookup.status === "ok" && compareVersions(version, lookup.latest) >= 0) {
+    lines.push("", "  Already on the latest published version.");
+  } else {
+    const target = lookup.status === "ok" ? lookup.latest : "latest";
+    lines.push(
+      "",
+      "  To update the global CLI:",
+      `    npm i -g ${name}@${target}`,
+      "  Or, in a project:",
+      `    pnpm add -D ${name}@${target}`,
+    );
+  }
+
+  lines.push("");
   // eslint-disable-next-line no-console
-  console.log(
-    `\n  Installed: gitpagedocs ${current}\n` +
-      "  To update the global CLI:\n" +
-      "    npm i -g gitpagedocs@latest\n" +
-      "  Or, in a project:\n" +
-      "    pnpm add -D gitpagedocs@latest\n",
-  );
+  console.log(lines.join("\n"));
 }