@rtorcato/repo-tooling 4.7.0 → 4.8.0

package/dist/base/secrets.js

@@ -0,0 +1,126 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { jobEnvironment, realGhExec, workflowJobs } from './github-settings.js';
+const WHERE_TO_GET = {
+    CODECOV_TOKEN: 'codecov.io -> your repo -> Settings -> Repository Upload Token',
+    RELEASE_TOKEN: 'a fine-grained PAT with contents: write (or a GitHub App token) that can push past branch protection',
+};
+const withoutComments = (s) => s
+    .split('\n')
+    .filter((l) => !l.trimStart().startsWith('#'))
+    .join('\n');
+function usesIn(text, file, job, environment) {
+    const clean = withoutComments(text);
+    const found = new Map();
+    for (const m of clean.matchAll(/secrets\.([A-Za-z_][A-Za-z0-9_]*)/g)) {
+        const name = m[1];
+        if (name === 'GITHUB_TOKEN' || found.has(name))
+            continue;
+        const fallback = new RegExp(`secrets\\.${name}\\s*\\|\\|\\s*secrets\\.GITHUB_TOKEN`).test(clean);
+        found.set(name, { name, file, job, environment, fallback });
+    }
+    return [...found.values()];
+}
+/** Every non-GITHUB_TOKEN secret the workflows (and a composite action.yml) reference. */
+export async function collectSecretUses(dir) {
+    const uses = [];
+    const wfDir = path.join(dir, '.github', 'workflows');
+    try {
+        const files = (await fs.pathExists(wfDir)) ? (await fs.readdir(wfDir)).sort() : [];
+        for (const f of files) {
+            if (!/\.ya?ml$/.test(f))
+                continue;
+            const content = await fs.readFile(path.join(wfDir, f), 'utf-8');
+            for (const [job, body] of workflowJobs(content)) {
+                uses.push(...usesIn(body, f, job, jobEnvironment(withoutComments(body))));
+            }
+        }
+        for (const a of ['action.yml', 'action.yaml']) {
+            const p = path.join(dir, a);
+            if (await fs.pathExists(p))
+                uses.push(...usesIn(await fs.readFile(p, 'utf-8'), a, '-', null));
+        }
+    }
+    catch {
+        return [];
+    }
+    return uses;
+}
+/** One entry per secret name, for setup's Next Steps. */
+export function requiredSecrets(uses) {
+    const byName = new Map();
+    for (const u of uses) {
+        const r = byName.get(u.name) ?? {
+            name: u.name,
+            usedBy: [],
+            whereToGet: WHERE_TO_GET[u.name] ?? null,
+            fallback: true,
+        };
+        if (!r.usedBy.includes(u.file))
+            r.usedBy.push(u.file);
+        r.fallback &&= u.fallback;
+        byName.set(u.name, r);
+    }
+    return [...byName.values()];
+}
+/** `gh secret set` lines plus where-to-get, for every secret in the list. */
+export function secretHints(secrets) {
+    return secrets.map((s) => `gh secret set ${s.name}${s.whereToGet ? `  # ${s.whereToGet}` : ''}`);
+}
+async function listNames(gh, endpoint) {
+    const r = await gh(['api', `${endpoint}?per_page=100`]);
+    if (!r.ok)
+        return null;
+    try {
+        const d = JSON.parse(r.stdout);
+        return new Set((d.secrets ?? []).flatMap((s) => (s.name ? [s.name] : [])));
+    }
+    catch {
+        return null;
+    }
+}
+const CHECK = 'Repository secrets';
+const skip = (why) => ({
+    check: CHECK,
+    status: 'ok',
+    detail: `not checked (${why})`,
+});
+export async function checkRepositorySecrets(dir, exec) {
+    if (!(await fs.pathExists(path.join(dir, '.git'))))
+        return skip('not a git repository');
+    const uses = await collectSecretUses(dir);
+    if (uses.length === 0)
+        return { check: CHECK, status: 'ok', detail: 'no secrets referenced' };
+    const gh = exec ?? ((args, stdin) => realGhExec(args, stdin, dir));
+    const repo = await listNames(gh, 'repos/{owner}/{repo}/actions/secrets');
+    if (!repo)
+        return skip("can't list secrets — needs gh with admin access");
+    // Best effort: an org scope that errors just contributes nothing.
+    const org = (await listNames(gh, 'repos/{owner}/{repo}/actions/organization-secrets')) ?? new Set();
+    const envs = new Map();
+    for (const e of new Set(uses.flatMap((u) => (u.environment ? [u.environment] : [])))) {
+        envs.set(e, await listNames(gh, `repos/{owner}/{repo}/environments/${e}/secrets`));
+    }
+    const missing = uses.filter((u) => {
+        if (repo.has(u.name) || org.has(u.name))
+            return false;
+        if (!u.environment)
+            return true;
+        const env = envs.get(u.environment);
+        // An unreadable environment can't prove absence.
+        return env ? !env.has(u.name) : false;
+    });
+    if (missing.length === 0) {
+        return { check: CHECK, status: 'ok', detail: 'all referenced secrets are set' };
+    }
+    const hard = missing.some((u) => !u.fallback);
+    const names = missing
+        .map((u) => `${u.name} (${u.file})${u.fallback ? ' [falls back to GITHUB_TOKEN]' : ''}`)
+        .join(', ');
+    return {
+        check: CHECK,
+        status: hard ? 'missing' : 'drift',
+        detail: `not set: ${names}. Dependabot-triggered runs read Dependabot secrets, not these`,
+        hint: secretHints(requiredSecrets(missing)).join('\n'),
+    };
+}

package/dist/cli/commands/doctor.js

@@ -14,6 +14,7 @@ import { SWIFT_GIT_HOOKS, runSwiftChecks } from '../../languages/swift/checks.js
 import { readSwiftPackage, renderSwiftWorkflow } from '../../languages/swift/ci.js';
 import { detectAuditLanguage } from '../utils/detect-language.js';
 import { checkGitHubSettings } from '../../base/github-settings.js';
+import { checkRepositorySecrets } from '../../base/secrets.js';
 import { checkMilestones } from '../../base/milestones.js';
 import { checkGitIdentity, checkGitIdentityHistory } from '../../base/git-identity.js';
 import { checkCopiedAssets } from '../utils/copied-assets.js';
@@ -211,6 +212,7 @@ async function runBaseChecks(dir, lock, opts) {
     // GitHub repo-settings drift (branch protection, merge settings, workflow
     // permissions). Read-only; self-skips as `ok` outside a live GitHub repo.
     results.push(...(await checkGitHubSettings(dir)));
+    results.push(await checkRepositorySecrets(dir));
     // Milestone hygiene (#397) — same seam, same self-skip.
     results.push(await checkMilestones(dir));
     results.push(await checkGitLabCI(dir));

package/dist/cli/commands/setup.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import chalk from 'chalk';
 import fs from 'fs-extra';
 import inquirer from 'inquirer';
+import { collectSecretUses, requiredSecrets, secretHints } from '../../base/secrets.js';
 import { formatNpmPublishGuide, npmPublishGuide, } from '../../languages/js/npm-trust.js';
 import { LANGUAGES } from '../../languages/registry.js';
 import { generateConfigs } from '../generators/index.js';
@@ -182,7 +183,7 @@ export async function setupProject(options) {
             await formatGeneratedFiles(config, targetDir);
         }
         console.log(chalk.green('\n✅ Setup completed successfully!\n'));
-        showNextSteps(config, targetDir);
+        await showNextSteps(config, targetDir);
     }
     catch (error) {
         console.error(chalk.red('\n❌ Setup failed:'), error);
@@ -580,7 +581,7 @@ export function npmPublishFor(config) {
         environment: null,
     });
 }
-function showNextSteps(config, _targetDir) {
+async function showNextSteps(config, targetDir) {
     console.log(chalk.bold('\n📋 Next Steps:\n'));
     const steps = [];
     // Every step in the else-branch names a pnpm script. Swift's equivalents are
@@ -615,6 +616,13 @@ function showNextSteps(config, _targetDir) {
         for (const line of formatNpmPublishGuide(npmPublish, true))
             console.log(`  ${line}`);
     }
+    const secrets = requiredSecrets(await collectSecretUses(targetDir));
+    if (secrets.length > 0) {
+        console.log(chalk.bold('\n🔐 GitHub setup (secrets the workflows need):\n'));
+        for (const line of secretHints(secrets))
+            console.log(`  ${line}`);
+        console.log('  Then: `fix github-settings` (branch protection), `fix release-environment` (release gate), and `doctor` to confirm');
+    }
     const skipped = collectSkippedFixSuggestions(config);
     if (skipped.length > 0) {
         console.log(chalk.bold('\n💡 Want to add something you skipped?\n'));

package/dist/cli/generators/docs-site.js

@@ -104,7 +104,7 @@ function jsString(value) {
         return JSON.stringify(value);
     return `'${JSON.stringify(value).slice(1, -1).replaceAll('\\"', '"').replaceAll("'", "\\'")}'`;
 }
-function docusaurusConfig(meta, typedocModules) {
+function docusaurusConfig(meta, typedocModules, siblings = []) {
     const owner = meta.owner ?? 'your-org';
     const repo = meta.repo ?? meta.title;
     const ghUrl = `https://github.com/${owner}/${repo}`;
@@ -116,6 +116,17 @@ function docusaurusConfig(meta, typedocModules) {
     const typedocPlugins = typedocModules.length
         ? `\t\t...getTypedocPlugins([${typedocModules.map(jsString).join(', ')}]),\n`
         : '';
+    const siblingNav = siblings
+        .map((s) => `\t\t\t\t{ href: ${jsString(s.href)}, label: ${jsString(s.label)}, position: 'left' },\n`)
+        .join('');
+    const siblingFooter = siblings.length
+        ? `\t\t\t\t{
+\t\t\t\t\ttitle: 'Projects',
+\t\t\t\t\titems: [
+${siblings.map((s) => `\t\t\t\t\t\t{ label: ${jsString(s.label)}, href: ${jsString(s.href)} },\n`).join('')}\t\t\t\t\t],
+\t\t\t\t},
+`
+        : '';
     return `import type * as Preset from '@docusaurus/preset-classic'
 import type { Config } from '@docusaurus/types'
 import { themes as prismThemes } from 'prism-react-renderer'
@@ -186,7 +197,7 @@ ${typedocPlugins}\t\t[
 \t\t\ttitle: '${meta.title}',
 \t\t\titems: [
 \t\t\t\t{ to: '/docs', position: 'left', label: 'Docs' },
-\t\t\t\t{
+${siblingNav}\t\t\t\t{
 \t\t\t\t\thref: '${ghUrl}',
 \t\t\t\t\tlabel: 'GitHub',
 \t\t\t\t\tposition: 'right',
@@ -207,7 +218,7 @@ ${typedocPlugins}\t\t[
 \t\t\t\t\t\t{ label: 'Issues', href: '${ghUrl}/issues' },
 \t\t\t\t\t],
 \t\t\t\t},
-\t\t\t],
+${siblingFooter}\t\t\t],
 \t\t\tcopyright: \`Copyright © \${new Date().getFullYear()} ${meta.title}. Built with Docusaurus.\`,
 \t\t},
 \t\t// \`theme\` is the LIGHT-mode Prism theme and \`darkTheme\` the dark one. Both
@@ -322,7 +333,10 @@ function docsPackageJson(meta, typedoc) {
     };
     return `${JSON.stringify(pkg, null, 2)}\n`;
 }
-function introDoc(meta, badges) {
+function introDoc(meta, badges, siblings = []) {
+    const related = siblings.length
+        ? `\n## Related projects\n\n${siblings.map((s) => `- [${s.label}](${s.href})`).join('\n')}\n`
+        : '';
     return `---
 title: ${meta.title}
 slug: /
@@ -336,7 +350,7 @@ ${meta.tagline}
 Welcome to the docs. Edit \`apps/docs/docs/intro.md\` to get started, and add
 more markdown files under \`apps/docs/docs/\` — they appear in the sidebar
 automatically.
-`;
+${related}`;
 }
 /** The per-repo workflow that drives the shared reusable deploy on push to main. */
 function docsWorkflow(meta) {
@@ -386,6 +400,7 @@ export default function Home() {
 export async function generateDocsSite(pkg, targetDir, options = {}) {
     const meta = inferSiteMeta(pkg);
     const accent = options.primaryColor ?? DEFAULT_ACCENT;
+    const siblings = options.siblings ?? [];
     const written = [];
     // Shared assets (only-if-missing copies of the shipped presets).
     written.push(...(await copyPresetIfMissing('docusaurus-sync-changelog', targetDir)));
@@ -409,12 +424,12 @@ export async function generateDocsSite(pkg, targetDir, options = {}) {
     // Project-specific scaffold.
     const files = [
         [`${DOCS_APP}/package.json`, docsPackageJson(meta, typedocModules.length > 0)],
-        [`${DOCS_APP}/docusaurus.config.ts`, docusaurusConfig(meta, typedocModules)],
+        [`${DOCS_APP}/docusaurus.config.ts`, docusaurusConfig(meta, typedocModules, siblings)],
         [`${DOCS_APP}/sidebars.ts`, SIDEBARS],
         [`${DOCS_APP}/tsconfig.json`, TSCONFIG],
         [`${DOCS_APP}/src/css/custom.css`, customCss(accent)],
         [`${DOCS_APP}/src/pages/index.tsx`, HOME_PAGE],
-        [`${DOCS_APP}/docs/intro.md`, introDoc(meta, badges)],
+        [`${DOCS_APP}/docs/intro.md`, introDoc(meta, badges, siblings)],
         ['.github/workflows/docs.yml', docsWorkflow(meta)],
     ];
     // TypeDoc emits docs/api/<id> on build — keep the generated tree out of git.

package/dist/cli/utils/lockfile.js

@@ -171,6 +171,26 @@ export function lockfileSchema() {
                             },
                         },
                     },
+                    docs: {
+                        type: 'object',
+                        additionalProperties: false,
+                        description: 'Inputs to `fix docs-site`.',
+                        properties: {
+                            siblings: {
+                                type: 'array',
+                                description: 'Sibling projects to link from the scaffolded docs site (navbar, footer, intro page). Opt-in: when absent the scaffold emits no such links.',
+                                items: {
+                                    type: 'object',
+                                    additionalProperties: false,
+                                    required: ['label', 'href'],
+                                    properties: {
+                                        label: { type: 'string', minLength: 1 },
+                                        href: { type: 'string', minLength: 1 },
+                                    },
+                                },
+                            },
+                        },
+                    },
                 },
             },
         },

package/dist/languages/js/fixers.js

@@ -76,7 +76,7 @@ import { generateDocsSite } from '../../cli/generators/docs-site.js';
 import { generateTypedocConfig, generateTypedocWorkflow } from '../../cli/generators/typedoc.js';
 import { copyPreset } from '../../cli/utils/copy-preset.js';
 import { identifiablePresetHashes } from '../../cli/utils/copied-assets.js';
-import { LOCKFILE_NAME, writeLockfile } from '../../cli/utils/lockfile.js';
+import { LOCKFILE_NAME, readLockfile, writeLockfile } from '../../cli/utils/lockfile.js';
 // The fixer contract moved to src/base/fixers.ts when Swift became the second
 // module (#286) — import it from there.
 import { FixerAbort } from '../../base/fixers.js';
@@ -774,7 +774,10 @@ export const FIXERS = [
                 }
             }
             const typedoc = hasTypedocConfig || 'typedoc' in deps;
-            const filesWritten = await generateDocsSite(pkg, targetDir, { typedoc });
+            const filesWritten = await generateDocsSite(pkg, targetDir, {
+                typedoc,
+                siblings: (await readLockfile(targetDir))?.rules?.docs?.siblings,
+            });
             return { filesWritten };
         },
     },

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "4.7.0",
+	"version": "4.8.0",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [