@inditextech/docouture-cli 0.1.0-SNAPSHOT.52.1 → 0.1.0-SNAPSHOT.63.1

package/build/commands/new.js

@@ -20,11 +20,11 @@ const NAME_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
 // releasable configurations handled by the templated docouture-release.yml — see
 // the docs-site-package skill's reference/versioning-modes.md. 'standalone'
 // (the default): `main` always builds as the prerelease/preview version, and
-// a release just force-moves a rolling `stable` tag — no historical archive,
+// a release just force-moves a rolling `docs/stable` tag — no historical archive,
 // appropriate for a product where only "now" and "what's next" matter.
 // 'versioned': `main` builds as the prerelease version too — docs/antora.yml
 // is identical to the standalone shape on main, for both modes — but every
-// release is instead its own immutable `vX.Y.Z` git tag, kept forever —
+// release is instead its own immutable `docs/vX.Y.Z` git tag, kept forever —
 // appropriate for a library/SDK whose consumers pin an old version. (A bare,
 // unversioned checkout — no prerelease/stable split at all — is not offered
 // here: it only ever comes up as an ad-hoc `docouture dev` preview before a mode
@@ -220,12 +220,12 @@ async function promptWizard(io, initial, defaults) {
                 {
                     name: 'Standalone (Stable + Prerelease)',
                     value: 'standalone',
-                    description: "main always builds as the prerelease/preview version; a release moves a rolling 'stable' tag — no historical archive kept.",
+                    description: "main always builds as the prerelease/preview version; a release moves a rolling 'docs/stable' tag — no historical archive kept.",
                 },
                 {
                     name: 'Versioned (Full History)',
                     value: 'versioned',
-                    description: 'main always builds as the prerelease/preview version; every release is an immutable vX.Y.Z git tag.',
+                    description: 'main always builds as the prerelease/preview version; every release is an immutable docs/vX.Y.Z git tag.',
                 },
             ],
         }, context));
@@ -394,6 +394,7 @@ export async function runNew(argv, io = defaultIO()) {
         pmLockfile: pm.lockfile,
         pmCiCmd: pm.ciCmd,
         pmSetupStepYaml: pm.setupStepYaml,
+        pmPackageManagerField: pm.packageManagerField,
         repoIgnoreGlob: repoIgnoreGlob(target),
     };
     // The whole starter subtree — package.json, antora-playbook.yml, its own
@@ -460,7 +461,7 @@ function printNextSteps(args) {
         console.log("    1. Create the 'docs/release' label (once): gh label create docs/release");
         console.log('    2. Open a PR that sets the target version in docs/.release-version (e.g. "1.0.0")');
         console.log("    3. Label the PR 'docs/release'");
-        console.log('    4. Merge it — docouture-release.yml runs automatically and tags vX.Y.Z');
+        console.log('    4. Merge it — docouture-release.yml runs automatically and tags docs/vX.Y.Z');
         console.log('');
         console.log('  (or skip the label/PR entirely: run docouture-release.yml manually via workflow_dispatch');
         console.log('  and type the version)');

package/build/commands/upgrade.js

@@ -108,6 +108,10 @@ export async function runUpgrade(argv) {
         pmLockfile: pm.lockfile,
         pmCiCmd: pm.ciCmd,
         pmSetupStepYaml: pm.setupStepYaml,
+        // Same reasoning as repoIgnoreGlob below: package.json (the only
+        // template file this placeholder appears in) is never re-copied by
+        // upgrade either, so there's nothing meaningful to compute it from.
+        pmPackageManagerField: 'unused-by-upgrade',
         // upgrade never re-copies docs/ (see below) — package.json, the only
         // template file this placeholder appears in, is never touched here — so
         // there's nothing meaningful to compute it from. Not an empty string:

package/build/lib/copy-template.js

@@ -22,6 +22,7 @@ const PLACEHOLDERS = {
     // value (which ends in its own `\n` — see packageManagerPlan) or the
     // empty npm value drop cleanly in its place.
     '      # __DOCOUTURE_PM_SETUP_STEP__\n': 'pmSetupStepYaml',
+    __DOCOUTURE_PM_PACKAGE_MANAGER__: 'pmPackageManagerField',
     // A bare token this time, unlike pmSetupStepYaml above — see
     // TemplateValues.repoIgnoreGlob's own comment for why the whole-segment
     // trick doesn't survive here.

package/build/lib/detect-package-manager.js

@@ -1,9 +1,34 @@
 'use strict';
+import { execFileSync } from 'node:child_process';
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 const PNPM_ACTION_SETUP_STEP = '      - name: Setup pnpm\n' +
-    '        uses: pnpm/action-setup@a3252b78c470c02f7abfb6128aa3c1852013d47c # v4\n' +
+    '        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4\n' +
+    '        with:\n' +
+    // `package_json_file` "must be relative to the repository root
+    // (GITHUB_WORKSPACE)" per the action's own action.yml — its default
+    // ('package.json') looks at the true repo root, not this site's own
+    // docs/package.json, even though `defaults.run.working-directory: docs`
+    // applies everywhere else in this workflow. Same gotcha, same fix as
+    // setup-node's `cache-dependency-path` a few lines below.
+    '          package_json_file: docs/package.json\n' +
     '\n';
+// The exact pnpm/npm version actually available wherever `docouture new` is
+// running — queried directly rather than guessed, so the `packageManager`
+// field this writes into the scaffolded package.json (see
+// packageManagerPlan below) is always a real, installable version. Falls
+// back to a pinned last-known-good version only if the binary can't be
+// queried at all (e.g. a test sandbox with neither on PATH) — degrading
+// gracefully rather than leaving the scaffold without a value that
+// `pnpm/action-setup` (CI) and corepack (locally) both need.
+function detectPackageManagerVersion(pm) {
+    try {
+        return execFileSync(pm, ['--version'], { encoding: 'utf8' }).trim();
+    }
+    catch {
+        return pm === 'pnpm' ? '10.24.0' : '10.9.2';
+    }
+}
 // Reads the invoking package manager off npm's own user-agent env var — set
 // by npm, pnpm and yarn alike on every script/exec they run, e.g.
 // 'pnpm/9.1.0 npm/? node/v20.11.0 darwin x64'. This is how `docouture new` was
@@ -64,6 +89,7 @@ export function packageManagerPlan(pm) {
             lockfile: 'pnpm-lock.yaml',
             cacheName: 'pnpm',
             setupStepYaml: PNPM_ACTION_SETUP_STEP,
+            packageManagerField: `pnpm@${detectPackageManagerVersion('pnpm')}`,
         };
     }
     return {
@@ -74,6 +100,7 @@ export function packageManagerPlan(pm) {
         lockfile: 'package-lock.json',
         cacheName: 'npm',
         setupStepYaml: '',
+        packageManagerField: `npm@${detectPackageManagerVersion('npm')}`,
     };
 }
 //# sourceMappingURL=detect-package-manager.js.map

package/build/lib/dev-server.js

@@ -309,7 +309,7 @@ export async function startDevServer(options) {
     log(`serving ${root}`);
     log(`  http://localhost:${port}${basePath}/`);
     const watchers = [
-        watchPath(join(siteRoot, 'docs')),
+        watchPath(join(siteRoot, 'src')),
         watchPath(join(siteRoot, 'antora-playbook.local.yml'), { recursive: false }),
     ];
     void Promise.all(watchers);

package/build/templates/starter/antora-playbook.local.yml

@@ -11,7 +11,7 @@
 # docouture docs-site-package skill's reference/versioning-modes.md), the real
 # `antora-playbook.yml` aggregates content from more than just whatever is
 # checked out right now — versioned matches `branches: [main]` +
-# `tags: ['v*']`, standalone matches `branches: [main]` + `tags: ['stable']`.
+# `tags: ['docs/v*']`, standalone matches `branches: [main]` + `tags: ['docs/stable']`.
 # A PR build (or a local build on a feature branch) is on a detached HEAD or
 # a branch that is neither of those, so `main` and the version tag(s) are
 # not resolved in that checkout — the real playbook either fails or silently

package/build/templates/starter/antora-playbook.versioned.yml

@@ -59,12 +59,12 @@ content:
       # version — docs/antora.yml on this branch says `version: prerelease`,
       # `prerelease: true`, the same as the standalone mode's shape (this
       # descriptor is identical for both modes on main — see docs/antora.yml's
-      # own comment). `tags: ['v*']` matches every release tag (v1.2.0,
-      # v2.0.0, ...) docouture-release.yml cuts, each an immutable version with
+      # own comment). `tags: ['docs/v*']` matches every release tag (docs/v1.2.0,
+      # docs/v2.0.0, ...) docouture-release.yml cuts, each an immutable version with
       # its own copy of docs/antora.yml — the version dropdown grows by one
       # every release and nothing here ever needs editing again.
       branches: [main]
-      tags: ['v*']
+      tags: ['docs/v*']
 
 ui:
   bundle:

package/build/templates/starter/antora-playbook.yml

@@ -60,13 +60,13 @@ content:
       start_path: docs/src
       # Standalone: `main` aggregates as the prerelease version —
       # docs/antora.yml on this branch permanently says `version: prerelease`,
-      # `prerelease: true`. `stable` is a rolling tag that docouture-release.yml
+      # `prerelease: true`. `docs/stable` is a rolling tag that docouture-release.yml
       # force-moves to a fresh one-off commit on every release, not a second
-      # long-lived branch. Until the first release, `stable` does not exist
+      # long-lived branch. Until the first release, `docs/stable` does not exist
       # yet and this site builds with just the one (prerelease) version —
       # that is expected, not an error.
       branches: [main]
-      tags: ['stable']
+      tags: ['docs/stable']
 
 ui:
   bundle:

package/build/templates/starter/package.json

@@ -7,6 +7,7 @@
   "engines": {
     "node": ">=24.0.0"
   },
+  "packageManager": "__DOCOUTURE_PM_PACKAGE_MANAGER__",
   "scripts": {
     "build": "antora --fetch antora-playbook.yml",
     "dev": "docouture dev",

package/build/templates/starter/src/modules/main/pages/getting-started.adoc

@@ -69,7 +69,7 @@ Two ways to trigger it:
   xref:main:prerequisites.adoc[] — otherwise the merge is a silent no-op.
 
 Under the hood this bumps the version recorded in `docs/antora.yml` and
-moves the `stable` tag (or, in Versioned mode, cuts a new `vX.Y.Z` tag) —
+moves the `docs/stable` tag (or, in Versioned mode, cuts a new `docs/vX.Y.Z` tag) —
 see that workflow's own header comment for the full mechanism.
 
 In *Versioned* mode, the target version for the *next* release is not typed
@@ -78,13 +78,13 @@ into a form — it comes from `docs/.release-version`, a plain-text file
 
 . Edit `docs/.release-version` so it contains `1.0.0`
 . Open a pull request with that change, labeled `docs/release`
-. Merge it — `docouture-release.yml` reads the file, tags `v1.0.0`, and bumps
+. Merge it — `docouture-release.yml` reads the file, tags `docs/v1.0.0`, and bumps
   `docs/.release-version` forward to the next patch version afterwards so
   the file is always ready for whatever comes next
 
 (Or skip the PR: run `docouture-release.yml` manually via `workflow_dispatch` and
 type the version into its `version` input.) *Standalone* mode has no such
-file — every release always targets the same `stable` tag, so there is
+file — every release always targets the same `docs/stable` tag, so there is
 nothing to set beforehand.
 
 `docouture version <value>` is a different, narrower tool: it directly

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

@@ -29,6 +29,15 @@ on:
   push:
     branches: ['main*']
 
+# Least-privilege default: this job only checks out `main`, warms the
+# Docker/Kroki image cache and writes it via actions/cache (a separate,
+# token-independent cache API, not repository contents) — it never uses
+# GITHUB_TOKEN itself, so it never needs more than read access. Declared
+# explicitly rather than left to inherit whatever the repository/
+# organization's default token permissions happen to be.
+permissions:
+  contents: read
+
 concurrency:
   group: docouture-kroki-cache-warm
   cancel-in-progress: true

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

@@ -19,6 +19,14 @@ name: docouture-pr-verify
 on:
   pull_request: {}
 
+# 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
+# on the PR, or otherwise uses GITHUB_TOKEN, so it never needs more than
+# read access. Declared explicitly rather than left to inherit whatever the
+# repository/organization's default token permissions happen to be.
+permissions:
+  contents: read
+
 concurrency:
   group: docouture-pr-verify-${{ github.event.pull_request.number }}
   cancel-in-progress: true

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

@@ -132,7 +132,24 @@ jobs:
       # specifically (unused, and unnecessary to set, for any other publish
       # target). See this file's own header comment for the `<target>`
       # naming convention and where its options come from.
+
+      # Mints an installation token for a GitHub App that's on this repo's
+      # branch-ruleset bypass list, if `gh-pages` is protected by one
+      # (branch rulesets requiring PRs / status checks) — see issue #157 in
+      # InditexTech/docouture. The plain GITHUB_TOKEN identity is never on a
+      # ruleset's own bypass list, so pushing `gh-pages` below is otherwise
+      # rejected (GH013) on a protected repo without this. `APP_CLIENT_ID`
+      # (a variable) and `APP_PRIVATE_KEY` (a secret) are organization-level
+      # in InditexTech — set both at the org or repo level for whichever
+      # GitHub App is bypass-listed on this site's rules.
+      - name: Git app token
+        id: app-token
+        uses: actions/create-github-app-token@v3
+        with:
+          client-id: ${{ vars.APP_CLIENT_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
       - name: Publish
         run: npx docouture publish gh-pages
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}

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

@@ -76,7 +76,7 @@ jobs:
             *"v*"*) mode=versioned ;;
             *stable*) mode=standalone ;;
             *)
-              echo "::error::antora-playbook.yml's content.sources[] has tags: '${line}' — expected something matching 'v*' (versioned) or 'stable' (standalone)."
+              echo "::error::antora-playbook.yml's content.sources[] has tags: '${line}' — expected something matching 'docs/v*' (versioned) or 'docs/stable' (standalone)."
               exit 1
               ;;
           esac
@@ -100,10 +100,10 @@ jobs:
             else
               version=""
             fi
-            tag="v${version}"
+            tag="docs/v${version}"
           else
             version="stable"
-            tag="stable"
+            tag="docs/stable"
           fi
 
           echo "version=${version}" >> "$GITHUB_OUTPUT"

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

@@ -3,8 +3,8 @@ name: docouture-release
 # Handles BOTH versioning modes — see the docouture docs-site-package skill's
 # versioning-modes.md for the full mechanism. Which mode a site is on is
 # detected, not asked: `docs/antora-playbook.yml`'s own content.sources[]
-# tags permanently say `tags: ['v*']` under versioned (Full History) or
-# `tags: ['stable']` under standalone (Stable + Prerelease) from the moment a
+# tags permanently say `tags: ['docs/v*']` under versioned (Full History) or
+# `tags: ['docs/stable']` under standalone (Stable + Prerelease) from the moment a
 # site opts into either — see the `Detect mode` step below. `docs/antora.yml`
 # on `main` is identical for both modes (`version: prerelease`,
 # `prerelease: true`) and is never read for this. Adopting a mode in the
@@ -14,8 +14,8 @@ name: docouture-release
 #
 # Prerequisite, done once, not by this workflow: this site's own
 # antora-playbook.yml content.sources[] must already match
-# `branches: [main]` + `tags: ['v*']` (versioned) or `branches: [main]` +
-# `tags: ['stable']` (standalone).
+# `branches: [main]` + `tags: ['docs/v*']` (versioned) or `branches: [main]` +
+# `tags: ['docs/stable']` (standalone).
 #
 # Two ways to run this, both deliberate acts rather than a side effect of an
 # ordinary push:
@@ -24,7 +24,7 @@ name: docouture-release
 #      (versioned) or leaves it as the default (standalone).
 #   2. Automatically, when a pull request carrying the `docs/release` label
 #      is merged into a branch matching `main*`. This path has no input to
-#      type a version into: standalone doesn't need one (always `stable`);
+#      type a version into: standalone doesn't need one (always `docs/stable`);
 #      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.
@@ -45,8 +45,8 @@ on:
       version:
         description: >-
           Target version for a versioned release, e.g. 1.2.0 (becomes tag
-          v1.2.0). Leave as 'stable' for a standalone site — that mode's
-          target is always the 'stable' tag, this input is ignored there.
+          docs/v1.2.0). Leave as 'stable' for a standalone site — that mode's
+          target is always the 'docs/stable' tag, this input is ignored there.
         required: true
         type: string
         default: 'stable'
@@ -103,13 +103,18 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
-          # Standalone moves an existing `stable` tag, which has to already
+          # Standalone moves an existing `docs/stable` tag, which has to already
           # be reachable in history to be force-moved. Versioned only ever
           # creates a brand-new tag on a brand-new commit and doesn't
           # strictly need this, but the detect step below needs main's tip
           # either way, and full history is harmless for that case.
           fetch-depth: 0
           ref: main
+          # Don't persist the ambient GITHUB_TOKEN's credentials — it isn't
+          # on this repo's branch-ruleset bypass list, and a local credential
+          # from actions/checkout would otherwise win over the app token's
+          # own credentials (set up below) when the git-push steps run.
+          persist-credentials: false
 
       # __DOCOUTURE_PM_SETUP_STEP__
       - name: Setup Node
@@ -194,9 +199,33 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
 
+      # Mints an installation token for a GitHub App that's on this repo's
+      # branch-ruleset bypass list, if `main`/`gh-pages` are protected by
+      # one (branch rulesets requiring PRs / status checks) — see issue #157
+      # in InditexTech/docouture. `Push release tag` and `Bump release
+      # descriptor` below both push straight to a branch/ref, and the plain
+      # GITHUB_TOKEN identity is never on a ruleset's own bypass list, so
+      # those pushes are rejected (GH013) on a protected repo without this.
+      # `APP_CLIENT_ID` (a variable) and `APP_PRIVATE_KEY` (a secret) are
+      # organization-level in InditexTech — set both at the org or repo
+      # level for whichever GitHub App is bypass-listed on this site's rules.
+      - name: Git app token
+        id: app-token
+        uses: actions/create-github-app-token@v3
+        with:
+          client-id: ${{ vars.APP_CLIENT_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+      - name: Git app credentials
+        env:
+          APP_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          git config --global credential.helper store
+          echo "https://x-access-token:${APP_TOKEN}@github.com" >> ~/.git-credentials
+
       # The one signal this workflow trusts: docs/antora-playbook.yml's own
-      # content.sources[] tags permanently say `tags: ['v*']` (versioned) or
-      # `tags: ['stable']` (standalone) from the moment a site opts into that
+      # content.sources[] tags permanently say `tags: ['docs/v*']` (versioned) or
+      # `tags: ['docs/stable']` (standalone) from the moment a site opts into that
       # mode — see this file's header and versioning-modes.md. Anything else
       # there is treated as misconfiguration, not a third mode. Unlike
       # docs/antora.yml elsewhere in this job — which really means
@@ -213,7 +242,7 @@ jobs:
             *"v*"*) mode=versioned ;;
             *stable*) mode=standalone ;;
             *)
-              echo "::error::antora-playbook.yml's content.sources[] has tags: '${line}' — expected something matching 'v*' (versioned) or 'stable' (standalone). See versioning-modes.md's 'Prerequisite' note."
+              echo "::error::antora-playbook.yml's content.sources[] has tags: '${line}' — expected something matching 'docs/v*' (versioned) or 'docs/stable' (standalone). See versioning-modes.md's 'Prerequisite' note."
               exit 1
               ;;
           esac
@@ -286,10 +315,10 @@ jobs:
         run: |
           if [ "$MODE" = "versioned" ]; then
             value="$VERSION"
-            tag="v${value}"
+            tag="docs/v${value}"
           else
             value="stable"
-            tag="stable"
+            tag="docs/stable"
           fi
 
           base=$(git rev-parse HEAD)
@@ -312,7 +341,7 @@ jobs:
       # (the tag already existed) must NOT bump docs/.release-version
       # forward, since that file already holds whatever was planned to come
       # after this republished version. Standalone has no equivalent need —
-      # `stable` is a rolling pointer, always overwritten, and there's no
+      # `docs/stable` is a rolling pointer, always overwritten, and there's no
       # release-version file to protect.
       - name: Check for existing release
         if: steps.detect.outputs.mode == 'versioned'
@@ -329,8 +358,8 @@ jobs:
           fi
 
       # Every release tag is force-recreated if it already exists — both
-      # modes, unconditionally. Standalone's `stable` is a rolling pointer by
-      # design; versioned's vX.Y.Z tags are meant to be immutable once
+      # modes, unconditionally. Standalone's `docs/stable` is a rolling pointer by
+      # design; versioned's docs/vX.Y.Z tags are meant to be immutable once
       # released, but a republish (fixing a released version) is a
       # deliberate, ordinary act here, not something gated behind a separate
       # flag or label.
@@ -343,7 +372,7 @@ jobs:
           git push origin "refs/tags/${TAG}" --force
 
       # Versioned only: every version is kept forever, so each one gets a
-      # real Release entry. Standalone deliberately skips this — `stable` is
+      # real Release entry. Standalone deliberately skips this — `docs/stable` is
       # a rolling pointer with no changelog value of its own, and that mode
       # keeps no version history to attach one to (see versioning-modes.md).
       # The delete-then-create is a no-op the first time a version is

package/package.json

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