@inditextech/docouture-cli 0.1.0-SNAPSHOT.90.1 → 1.1.0

package/build/bin.js

@@ -137,8 +137,9 @@ Example:
   docouture doctor [--dir <path>] [--json]
 
 Check that the environment and site configuration are healthy: Node
-version, the four names that must agree (component name, start page,
-content path, package name), git history, that antora is installed,
+version, that the declared package manager (package.json's packageManager
+field) is installed, the four names that must agree (component name, start
+page, content path, package name), git history, that antora is installed,
 and (advisory only) whether AGENTS.md and the scaffolded skills are
 still present, whether the docs/release label exists, and whether the
 declared branching model (docs/package.json's docouture.branching)

package/build/commands/branch-model.js

@@ -161,6 +161,11 @@ export async function runBranchModel(argv) {
         // there is nothing meaningful to compute either from.
         componentName: 'unused-by-branch-model',
         cliVersion,
+        // .tool-versions (the only template file these two placeholders appear
+        // in) is never re-copied by branch-model — same reasoning as
+        // componentName above.
+        nodeVersion: 'unused-by-branch-model',
+        pnpmToolVersionsLine: 'unused-by-branch-model',
         pmName: pm.pm,
         pmCacheName: pm.cacheName,
         pmLockfile: pm.lockfile,

package/build/commands/doctor.js

@@ -11,7 +11,7 @@ import { getContext } from '../lib/cli-context.js';
 import { theme } from '../lib/theme.js';
 import { readSourceUrl, readStartPageComponent, readStartPath } from '../lib/playbook-yml.js';
 import { detectBranches, inferBranching } from '../lib/branch-detect.js';
-import { checkAgentFilesPresent, checkAntoraAvailable, checkBranchingAgrees, checkGitHasCommit, checkNamesAgree, checkNodeVersion, checkReleaseLabelExists, } from '../lib/doctor-checks.js';
+import { checkAgentFilesPresent, checkAntoraAvailable, checkBranchingAgrees, checkGitHasCommit, checkNamesAgree, checkNodeVersion, checkPackageManagerAvailable, checkReleaseLabelExists, } from '../lib/doctor-checks.js';
 async function readJson(file) {
     try {
         return JSON.parse(await readFile(file, 'utf8'));
@@ -82,6 +82,10 @@ export async function runDoctor(argv) {
     status |= record(report, 'toolchain', nodeResult, 'fail');
     if (!json)
         printResult(nodeResult);
+    const pmResult = await checkPackageManagerAvailable(pkg?.packageManager ?? null);
+    status |= record(report, 'toolchain', pmResult, 'fail');
+    if (!json)
+        printResult(pmResult);
     log('names');
     const playbookFile = join(siteRoot, 'antora-playbook.yml');
     const antoraYmlFile = join(siteRoot, 'src', 'antora.yml');

package/build/commands/new.js

@@ -475,11 +475,20 @@ export async function runNew(argv, io = defaultIO()) {
     // it always matches whatever CLI actually generated it, snapshot/local
     // releases included.
     const { version: cliVersion } = await readCliInfo(import.meta.url, 2);
+    // Whatever Node is actually running this scaffold — same reasoning as
+    // cliVersion above (readCliInfo's own comment), just for the runtime
+    // rather than the CLI package. Written as .tool-versions' `nodejs` line.
+    const nodeVersion = process.version.replace(/^v/, '');
     // The user's own choice (--pm, wizard answer, or the auto-guess computed
     // above if neither was given) — never re-detected against `target`, so
     // whatever was actually chosen/confirmed is what the workflows and
     // printed next-steps agree on.
     const pm = packageManagerPlan(pmChoice);
+    // .tool-versions' second line — present only for a pnpm-scaffolded site
+    // (see TemplateValues.pnpmToolVersionsLine's own comment); pm.packageManagerField
+    // is already the corepack-convention 'pnpm@<version>' string, so this
+    // just reshapes it into asdf/mise's own 'pnpm <version>' line syntax.
+    const pnpmToolVersionsLine = pm.pm === 'pnpm' ? `pnpm ${pm.packageManagerField.split('@')[1]}\n` : '';
     const values = {
         name,
         title,
@@ -494,6 +503,8 @@ export async function runNew(argv, io = defaultIO()) {
         // component-name check when this is the literal 'ROOT'.
         componentName: urlSegment ? name : 'ROOT',
         cliVersion,
+        nodeVersion,
+        pnpmToolVersionsLine,
         pmName: pm.pm,
         pmCacheName: pm.cacheName,
         pmLockfile: pm.lockfile,

package/build/commands/upgrade.js

@@ -68,6 +68,14 @@ export async function runUpgrade(argv) {
     const templatesRoot = join(here, '..', 'templates');
     const workflowsTemplateDir = join(templatesRoot, 'workflows');
     const agentSupportDir = join(templatesRoot, 'agent-support');
+    // Unlike the rest of `docs/` (never re-copied — see the comment above the
+    // dry-run/real-run split below), `scripts/check-links.mjs` gets the same
+    // "regenerate wholesale" treatment as workflows: it carries zero
+    // `__DOCOUTURE_*__` placeholder tokens (nothing site-specific to lose),
+    // and its own comments already say the one thing a site owner is meant
+    // to customise — which links to ignore — belongs in package.json's
+    // `docouture.checkLinks.ignore`, not in edits to the script body itself.
+    const scriptsTemplateDir = join(templatesRoot, 'starter', 'scripts');
     // build/commands/upgrade.js -> package root, 2 levels up — see
     // readCliInfo's own comment. Always re-read fresh: an upgrade run re-pins
     // whatever templates reference the CLI version to the one actually
@@ -119,6 +127,12 @@ export async function runUpgrade(argv) {
         // substituted anywhere upgrade touches.
         componentName: 'unused-by-upgrade',
         cliVersion,
+        // .tool-versions (the only template file these two placeholders appear
+        // in) is never re-copied by upgrade — same reasoning as componentName
+        // above: structurally required by TemplateValues, but nothing
+        // meaningful to compute either from here.
+        nodeVersion: 'unused-by-upgrade',
+        pnpmToolVersionsLine: 'unused-by-upgrade',
         pmName: pm.pm,
         pmCacheName: pm.cacheName,
         pmLockfile: pm.lockfile,
@@ -145,30 +159,36 @@ export async function runUpgrade(argv) {
     };
     const workflowsDir = join(target, '.github', 'workflows');
     const agentsMdFile = join(target, AGENTS_MD_FILENAME);
+    const scriptsDir = join(target, 'docs', 'scripts');
     // Unlike `new.ts`, this command's whole purpose is to overwrite what's
     // already there — workflows are meant to be regenerable from the
     // template on every upgrade, not merged with local edits (there is no
     // content-hash/diff tracking anywhere in this CLI to tell a stock file
     // from a user-edited one). `docs/` itself — the starter content a site
-    // has since written its own pages into — is never touched here. Skills
+    // has since written its own pages into — is never touched here, with one
+    // exception: `docs/scripts/` gets the same blind-overwrite treatment as
+    // workflows (see scriptsTemplateDir's own comment above for why). Skills
     // are never touched here either: `docouture upgrade` only re-syncs the
     // starter site and its GitHub workflows, same as `docouture new` only
     // scaffolds them — skills are a separate, self-serve install via
-    // `npx skills add InditexTech/docouture`. AGENTS.md is the one exception:
-    // copyTemplate's own SKIP_FILENAMES skip (see copy-template.ts) leaves it
-    // untouched by the walk above, and it's merged instead — see
-    // lib/agents-md.ts for why a blind overwrite here would silently destroy
-    // the 'Documentation state' table the docouture-documenting-changes skill
-    // maintains outside docouture' own managed section.
+    // `npx skills add InditexTech/docouture`. AGENTS.md is the other
+    // exception: copyTemplate's own SKIP_FILENAMES skip (see
+    // copy-template.ts) leaves it untouched by the walk above, and it's
+    // merged instead — see lib/agents-md.ts for why a blind overwrite here
+    // would silently destroy the 'Documentation state' table the
+    // docouture-documenting-changes skill maintains outside docouture' own
+    // managed section.
     if (dryRun) {
         const plannedWorkflows = await copyTemplate(workflowsTemplateDir, workflowsDir, values, { dryRun: true });
+        const plannedScripts = await copyTemplate(scriptsTemplateDir, scriptsDir, values, { dryRun: true });
         console.log('would write:');
-        for (const path of [...plannedWorkflows, agentsMdFile]) {
+        for (const path of [...plannedWorkflows, ...plannedScripts, agentsMdFile]) {
             console.log(`  ${relative(target, path)}`);
         }
         return 0;
     }
     await copyTemplate(workflowsTemplateDir, workflowsDir, values);
+    await copyTemplate(scriptsTemplateDir, scriptsDir, values);
     const existingAgentsMd = (await exists(agentsMdFile)) ? await readFile(agentsMdFile, 'utf8') : undefined;
     const renderedAgentsMd = await renderTemplateFile(join(agentSupportDir, AGENTS_MD_FILENAME), values);
     await writeFile(agentsMdFile, mergeAgentsMd(existingAgentsMd, renderedAgentsMd), 'utf8');
@@ -177,6 +197,7 @@ export async function runUpgrade(argv) {
     // relative(cwd, ...) produces a useless '../../..' chain for paths that
     // are actually just '.github/workflows', 'AGENTS.md' etc. at the root.
     console.log(`updated ${relative(target, workflowsDir)}`);
+    console.log(`updated ${relative(target, scriptsDir)}`);
     console.log(`updated ${relative(target, agentsMdFile)}`);
     return 0;
 }

package/build/lib/agents-md.js

@@ -64,7 +64,15 @@ export function mergeAgentsMd(existing, templateContent) {
         const after = existing.slice(end + MANAGED_END.length);
         return `${before}${extractManagedBlock(templateContent)}${after}`;
     }
-    const separator = existing.length === 0 ? '' : existing.endsWith('\n\n') ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
+    let separator;
+    if (existing.length === 0)
+        separator = '';
+    else if (existing.endsWith('\n\n'))
+        separator = '';
+    else if (existing.endsWith('\n'))
+        separator = '\n';
+    else
+        separator = '\n\n';
     return `${existing}${separator}${templateContent}`;
 }
 //# sourceMappingURL=agents-md.js.map

package/build/lib/copy-template.js

@@ -9,6 +9,12 @@ const PLACEHOLDERS = {
     __DOCOUTURE_TITLE__: 'title',
     __DOCOUTURE_COMPONENT_NAME__: 'componentName',
     __DOCOUTURE_CLI_VERSION__: 'cliVersion',
+    __DOCOUTURE_NODE_VERSION__: 'nodeVersion',
+    // Whole-line token, same reasoning as pmSetupStepYaml's own comment below
+    // — the value (or '' for npm) already carries its own trailing newline,
+    // so substituting the token-plus-newline is what lets the line vanish
+    // entirely rather than leaving a blank line in the npm case.
+    '__DOCOUTURE_PNPM_TOOL_VERSIONS_LINE__\n': 'pnpmToolVersionsLine',
     __DOCOUTURE_PM__: 'pmName',
     __DOCOUTURE_PM_CACHE__: 'pmCacheName',
     __DOCOUTURE_LOCKFILE__: 'pmLockfile',

package/build/lib/dev-server.js

@@ -365,7 +365,7 @@ export async function startDevServer(options) {
             // otherwise be left running as an orphan after the dev server itself
             // has already torn down — kill it too, best-effort (it may already
             // have exited on its own by the time close() runs).
-            if (activeBuildChild && activeBuildChild.exitCode === null && !activeBuildChild.killed) {
+            if (activeBuildChild?.exitCode === null && !activeBuildChild?.killed) {
                 activeBuildChild.kill('SIGTERM');
             }
             for (const res of clients)

package/build/lib/doctor-checks.js

@@ -37,6 +37,51 @@ export function checkNodeVersion(engineRange, actualVersion) {
         detail: `install Node ${wantMajor} or newer — this is what 'npm run build'/'docouture dev' will actually run under`,
     };
 }
+/**
+ * Confirms the package manager a site actually declares (`package.json`'s
+ * own `packageManager` field, corepack convention, e.g. `pnpm@10.24.0`) is
+ * installed and reachable — `checkNodeVersion` above gets a shortcut
+ * (`docouture` *is* a Node process, so Node's presence is proof positive,
+ * only its version is an open question), but `docouture` doesn't run *as*
+ * npm or pnpm, so their presence has to be checked by actually spawning the
+ * binary. Presence only — no version-match against the declared field is
+ * required, the field just says which binary to look for.
+ *
+ * The `<name>` before `@` is read as-is rather than restricted to a
+ * hardcoded `npm`/`pnpm` allow-list — this is what `docouture new` ever
+ * writes there in practice, but nothing here depends on that being true.
+ */
+export function checkPackageManagerAvailable(packageManagerField) {
+    const label = 'package manager';
+    if (!packageManagerField) {
+        return Promise.resolve({
+            ok: true,
+            label,
+            message: 'no packageManager field declared in package.json — skipping',
+        });
+    }
+    const match = /^([^@\s]+)@/.exec(packageManagerField);
+    const pm = match?.[1];
+    if (!pm) {
+        return Promise.resolve({
+            ok: true,
+            label,
+            message: `could not parse packageManager '${packageManagerField}' — skipping`,
+        });
+    }
+    return new Promise((resolvePromise) => {
+        execFile(pm, ['--version'], { timeout: 10_000 }, (err, stdout) => {
+            resolvePromise(err
+                ? {
+                    ok: false,
+                    label,
+                    message: `'${pm}' is not available on PATH`,
+                    detail: `package.json declares packageManager: '${packageManagerField}' — install ${pm} (or run via corepack)`,
+                }
+                : { ok: true, label, message: `${pm} ${stdout.trim()} is available` });
+        });
+    });
+}
 /**
  * The four names the docs-site-package skill documents as having to agree,
  * or a site builds to zero pages, or dies on "start page not found" — see

package/build/templates/starter/.tool-versions

@@ -0,0 +1,2 @@
+nodejs __DOCOUTURE_NODE_VERSION__
+__DOCOUTURE_PNPM_TOOL_VERSIONS_LINE__

package/build/templates/starter/gitignore

@@ -1,3 +1,4 @@
 node_modules/
 build/
 .DS_Store
+.npmrc

package/build/templates/starter/scripts/check-links.mjs

@@ -63,8 +63,8 @@ const isExternal = (url) => /^https?:\/\//.test(url)
 // every other regex metacharacter so the rest of the string is matched
 // verbatim.
 function globToRegExp(glob) {
-  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&')
-  return new RegExp(escaped.replace(/\*/g, '.*').replace(/\?/g, '.'))
+  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, String.raw`\$&`)
+  return new RegExp(escaped.replaceAll('*', '.*').replaceAll('?', '.'))
 }
 
 // `package.json`'s own "docouture" config block (see the scaffolded stub, next
@@ -140,6 +140,28 @@ const result = await check({
   path: 'build/site',
   recurse: true,
   linksToSkip: SKIP,
+  // linkinator's own default is 0 — NO application-level timeout at all
+  // (see its own README: "requests made by linkinator do not time out, or
+  // follow the settings of the OS"), which means `request.js`'s
+  // `AbortSignal.timeout(options.timeout)` is never even constructed. A
+  // real multi-page site can easily produce a few hundred *distinct*
+  // (not duplicate — linkinator already dedupes identical URLs, so this
+  // isn't a dedup gap) links to the same external host: think a
+  // CHANGELOG page with one github.com/…/pull/NNN link per entry, not
+  // just this template's own repo-link/edit-link. A burst that size can
+  // trip a host's own anonymous-crawler rate limiting (GitHub's included),
+  // and — unconfirmed upstream, but plausible and cheap to guard against
+  // either way — if that limiting responds slowly rather than rejecting
+  // fast, an unbounded request ties up one of `concurrency`'s 100 slots
+  // for however long the OS's own idle/keepalive timeout happens to be
+  // (which can be minutes), not a few seconds. 10s is generous for any
+  // real external page load; it only ever kicks in to cut a stalled
+  // socket loose instead of quietly inflating the whole crawl's wall-clock
+  // time. NOT a fix for "too many links to github.com" in general — those
+  // are real, individually-distinct links an author is vouching for, and
+  // correctly stay off `docouture.checkLinks.ignore` (see ignorePatterns()
+  // above) so a genuinely broken one still fails the build.
+  timeout: 10_000,
   // A plain 403/429 from a real external host (most commonly GitHub's own
   // bot/rate-limit protection kicking in on repo links, hit repeatedly
   // across every page of a freshly built site) can't be told apart from a

package/build/templates/workflows/docouture-kroki-cache-warm.yml

@@ -37,9 +37,17 @@ name: docouture-kroki-cache-warm
 #
 # Gated on `kroki-enabled` the same way those three are — no point warming a
 # cache for images a disabled site's build will never touch.
+#
+# Path-filtered for the same reason docouture-pr-verify.yml is: a push that
+# touches neither `docs/` nor this file has nothing for this job to usefully
+# warm a cache for. Nothing else in this repo depends on this job running,
+# so skipping it entirely (rather than a no-op run) is safe by construction.
 on:
   push:
     branches: [__DOCOUTURE_CACHE_WARM_BRANCHES__]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docouture-kroki-cache-warm.yml'
 
 # Least-privilege default: this job only checks out the release/prerelease
 # branch it happened to run against, warms the Docker/Kroki image cache and

package/build/templates/workflows/docouture-pr-verify.yml

@@ -16,8 +16,19 @@ name: docouture-pr-verify
 # that file's own header) exists for exactly this: one content source,
 # `branches: HEAD`, so this always validates whatever the PR actually
 # changed — no `fetch-depth: 0` needed, since no other ref is ever read.
+#
+# Path-filtered so it doesn't run at all on a PR that touches neither `docs/`
+# content nor this file — nothing else in this job's build can be affected by
+# changes elsewhere in the repo. If this job (`Verify`, this workflow) is a
+# required status check in your own branch protection, confirm that's set up
+# to tolerate a skipped run (e.g. GitHub's "Do not require status checks on
+# creation" / rulesets' own equivalent) rather than blocking merges on a
+# check that now never reports for docs-untouched PRs.
 on:
-  pull_request: {}
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docouture-pr-verify.yml'
 
 # Least-privilege default: this job only checks out the PR's own HEAD,
 # builds it, and checks links — it never writes to the repository, comments

package/build/templates/workflows/docouture-release-preview.yml

@@ -24,7 +24,11 @@ on:
     branches: ['__DOCOUTURE_RELEASE_BRANCH__*']
 
 concurrency:
-  group: release-preview
+  # Scoped per-PR, not just per-workflow: a bare 'release-preview' group name
+  # collides with this monorepo's own code-release_preview.yml, so a label
+  # change firing both workflows at once could have one cancel the other
+  # mid-run even though they preview unrelated releases.
+  group: docouture-release-preview-${{ github.event.pull_request.number }}
   cancel-in-progress: true
 
 jobs:
@@ -148,6 +152,20 @@ jobs:
             exit 0
           fi
 
+          # Same full SemVer 2.0.0 grammar docouture-release.yml's own
+          # "Validate version" step checks — see that step's own comment for
+          # why plain groups instead of `(?:...)` (bash's [[ =~ ]] runs glibc
+          # POSIX ERE, not PCRE). Catching this here, before merge, is the
+          # whole point of a preview: docouture-release.yml checks the same
+          # thing, but only finds out after the PR has already merged.
+          SEMVER_RE='^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-(0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)(\.(0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*))*)?(\+[0-9a-zA-Z-]+(\.[0-9a-zA-Z-]+)*)?$'
+          if [ "$MODE" = "versioned" ] && ! [[ "$VERSION" =~ $SEMVER_RE ]]; then
+            gh pr comment ${{ github.event.number }} --body "
+          ### :x: docs/release: invalid target version
+          \`docs/.release-version\` contains \`${VERSION}\`, which is not a valid SemVer version — use something like \`1.2.0\` (see https://semver.org). A leading \`v\` or a two-part \`1.2\` are not valid; the release workflow will fail on merge otherwise."
+            exit 0
+          fi
+
           MESSAGE="
           ### :rocket: Docs Release Preview
           Merging this Pull Request will release the docs site as **\`${TAG}\`**."

package/build/templates/workflows/docouture-release.yml

@@ -302,6 +302,25 @@ jobs:
             exit 1
           fi
 
+          # Full SemVer 2.0.0 grammar (semver.org's own regex, rewritten with
+          # plain groups instead of `(?:...)` — bash's [[ =~ ]] runs glibc
+          # POSIX ERE, not PCRE, and doesn't understand non-capturing
+          # groups). Catches a hand-edited docs/.release-version (or a typo'd
+          # workflow_dispatch input) BEFORE any tag is pushed below — without
+          # this, a malformed value sails through here, tags and pushes fine
+          # in "Cut release"/"Push release tag", and only fails later inside
+          # "Bump release descriptor" (npm's `version patch` rejects
+          # non-semver input) — by which point the tag already exists but the
+          # job as a whole reads as failed, so the `publish` job below never
+          # runs. Prerelease/build-metadata suffixes (1.2.0-beta.1,
+          # 1.2.0+build) are valid SemVer and accepted; a leading 'v' or a
+          # bare '1.2' are not.
+          SEMVER_RE='^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-(0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)(\.(0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*))*)?(\+[0-9a-zA-Z-]+(\.[0-9a-zA-Z-]+)*)?$'
+          if [ "$MODE" = "versioned" ] && [ -n "$VERSION" ] && ! [[ "$VERSION" =~ $SEMVER_RE ]]; then
+            echo "::error::docs/.release-version (or the 'version' input) must be a valid SemVer version like 1.2.0 — got '${VERSION}'. See https://semver.org — prerelease/build metadata (1.2.0-beta.1, 1.2.0+build) is fine, a leading 'v' or a two-part '1.2' is not."
+            exit 1
+          fi
+
           if [ "$MODE" = "standalone" ] && [ -n "$VERSION" ] && [ "$VERSION" != "stable" ]; then
             echo "::warning::Standalone mode always releases to the 'stable' tag — ignoring provided version '${VERSION}'."
           fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inditextech/docouture-cli",
-  "version": "0.1.0-SNAPSHOT.90.1",
+  "version": "1.1.0",
   "description": "Command-line tool for docouture documentation sites: scaffold a new site and set its Antora version outside the monorepo",
   "repository": {
     "type": "git",