@inditextech/docouture-cli 1.0.0 → 1.1.1

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
@@ -151,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');
@@ -183,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/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/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

@@ -152,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

@@ -20,7 +20,7 @@ name: docouture-release
 # branch roles mean (trunk-based: both the same branch; git-flow: two
 # independently-named branches, e.g. `develop`/`main`).
 #
-# Two ways to run this, both deliberate acts rather than a side effect of an
+# Three ways to run this, all deliberate acts rather than a side effect of an
 # ordinary push:
 #
 #   1. workflow_dispatch — a person runs it by hand and supplies `version`
@@ -32,6 +32,28 @@ name: docouture-release
 #      versioned reads it from `docs/.release-version`, a plain-text file
 #      the PR itself commits with the target version — reviewed as part of
 #      that PR's diff, like any other change.
+#   3. Automatically, whenever a GitHub Release is published on this repo.
+#      Irrelevant unless this repo ALSO cuts its own code releases some other
+#      way, labelling the merged PR `release-type/*` (optionally
+#      `skip-release`) the way docouture's own repo does — nothing scaffolds
+#      that convention here, so on a fresh `docouture new` site this trigger
+#      simply never fires and the job below always takes path #2 instead.
+#      Kept anyway, disabled by omission rather than left out, so adopting
+#      that convention later is a label/workflow change only, not a rewrite
+#      of this file too.
+#
+#      Where it does apply: this overlaps with #2 — a single merged PR can
+#      carry BOTH `docs/release` and a `release-type/*` label (releasing
+#      code and docs together). If it did, and #2 fired unconditionally,
+#      this workflow would run twice for the one merge — once immediately
+#      (the `pull_request` close) and again once that other release job
+#      finishes and publishes its Release (the trigger added here). The
+#      job's own `if:` below avoids that: the `pull_request` branch only
+#      fires when a code release is NOT also about to happen for the same
+#      merge (no `release-type/*` label, or `skip-release` overrides it) —
+#      otherwise it backs off and leaves the job to trigger #3 instead, once
+#      that other workflow actually finishes. Either way this runs exactly
+#      once per merge, just not always at the same moment.
 #
 # Republishing (versioned only): a fix that needs to land on an
 # already-released version overwrites that version's tag — this workflow
@@ -57,6 +79,8 @@ on:
   pull_request:
     types: [closed]
     branches: ['__DOCOUTURE_RELEASE_BRANCH__*']
+  release:
+    types: [published]
 
 permissions:
   contents: write
@@ -81,16 +105,23 @@ jobs:
     defaults:
       run:
         working-directory: docs
-    # workflow_dispatch always proceeds (it's already an explicit, deliberate
-    # act). The pull_request trigger fires on every close of a PR targeting
-    # the release branch — including ones that were closed unmerged, or
-    # merged without the label — so it only proceeds when both are true:
-    # actually merged, and carrying `docs/release`. Anything else is a
-    # no-op run, not an error.
+    # workflow_dispatch and a published Release both always proceed (already
+    # explicit, deliberate acts). The pull_request trigger fires on every
+    # close of a PR targeting the release branch — including ones that were
+    # closed unmerged, or merged without the label — so it only proceeds
+    # when merged, carrying `docs/release`, AND a same-merge code release is
+    # NOT also about to fire under the `release-type`/`skip-release`
+    # convention (see this file's own header comment on trigger #2/#3 — a
+    # no-op on a site that doesn't use that convention, since
+    # `release-type`/`skip-release` labels then never exist to contain).
+    # Anything else is a no-op run, not an error.
     if: >-
       github.event_name == 'workflow_dispatch' ||
+      github.event_name == 'release' ||
       (github.event.pull_request.merged == true &&
-        contains(github.event.pull_request.labels.*.name, 'docs/release'))
+        contains(github.event.pull_request.labels.*.name, 'docs/release') &&
+        (contains(github.event.pull_request.labels.*.name, 'skip-release') ||
+          !contains(join(github.event.pull_request.labels.*.name, ', '), 'release-type')))
     steps:
       - name: Require release branch
         # Only meaningful for a manual dispatch: someone could run this
@@ -302,6 +333,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": "1.0.0",
+  "version": "1.1.1",
   "description": "Command-line tool for docouture documentation sites: scaffold a new site and set its Antora version outside the monorepo",
   "repository": {
     "type": "git",