@micazoyolli/foundation 0.3.2 → 0.4.1

package/README.md

@@ -19,6 +19,7 @@ La documentación principal vive en [foundation.nadia.dev](https://foundation.na
 - Helpers DOM para metadata client-side.
 - Primitivas de accesibilidad para focus, Escape, scroll lock y media protegida.
 - Helpers SEO/build para canonical, sitemap, HTML estático y escaping.
+- CLI de build para publicar `dist` en GitHub Pages sin crear commits en la rama fuente.
 - Sin dependencias runtime pesadas y sin React.
 
 ## Instalación
@@ -72,6 +73,14 @@ yarn test
 yarn docs:build
 ```
 
+## CLI
+
+```bash
+micazoyolli-gh-pages-deploy
+```
+
+El CLI publica `dist` en `origin/gh-pages` desde un worktree temporal. Es tooling de build/deploy, no un export runtime.
+
 ## Autoría
 
 Una creación de [`<micazoyolli />`](https://nadia.dev)

package/dist/cli/deploy-github-pages.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/deploy-github-pages.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { deployGithubPages, GithubPagesDeployError } from '../git/githubPagesDeploy.js';
+const main = async () => {
+    console.log('Deploying dist to origin/gh-pages...');
+    const result = await deployGithubPages();
+    if (!result.pushed) {
+        console.log(result.reason ?? 'No deployment commit was necessary.');
+        console.log('Repository left unchanged.');
+        return;
+    }
+    console.log(`${result.initialDeployment ? 'Created' : 'Published'} ${result.commit} to ${result.remote}/${result.deploymentBranch}.`);
+    console.log('Repository left clean on main.');
+};
+main().catch((error) => {
+    if (error instanceof GithubPagesDeployError) {
+        console.error(`Deployment failed: ${error.message}`);
+    }
+    else if (error instanceof Error) {
+        console.error(`Deployment failed: ${error.message}`);
+    }
+    else {
+        console.error('Deployment failed with an unknown error.');
+    }
+    process.exitCode = 1;
+});

package/dist/git/githubPagesDeploy.d.ts

@@ -0,0 +1,21 @@
+export type GithubPagesDeployOptions = {
+    buildDir?: string;
+    deploymentBranch?: string;
+    message?: string;
+    remote?: string;
+    sourceBranch?: string;
+    cwd?: string;
+};
+export type GithubPagesDeployResult = {
+    commit?: string;
+    deploymentBranch: string;
+    initialDeployment: boolean;
+    pushed: boolean;
+    reason?: string;
+    remote: string;
+    repositoryRoot: string;
+};
+export declare class GithubPagesDeployError extends Error {
+    constructor(message: string);
+}
+export declare const deployGithubPages: (options?: GithubPagesDeployOptions) => Promise<GithubPagesDeployResult>;

package/dist/git/githubPagesDeploy.js

@@ -0,0 +1,216 @@
+import { cp, mkdtemp, readdir, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { spawnSync } from 'node:child_process';
+const DEFAULT_BUILD_DIR = 'dist';
+const DEFAULT_DEPLOYMENT_BRANCH = 'gh-pages';
+const DEFAULT_MESSAGE = 'build: dist actualizado correctamente';
+const DEFAULT_REMOTE = 'origin';
+const DEFAULT_SOURCE_BRANCH = 'main';
+export class GithubPagesDeployError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GithubPagesDeployError';
+    }
+}
+const resolveOptions = (options = {}) => ({
+    buildDir: options.buildDir ?? DEFAULT_BUILD_DIR,
+    cwd: options.cwd ?? process.cwd(),
+    deploymentBranch: options.deploymentBranch ?? DEFAULT_DEPLOYMENT_BRANCH,
+    message: options.message ?? DEFAULT_MESSAGE,
+    remote: options.remote ?? DEFAULT_REMOTE,
+    sourceBranch: options.sourceBranch ?? DEFAULT_SOURCE_BRANCH,
+});
+const assertSafeGitRefPart = (value, label) => {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(value) || value.includes('..') || value.endsWith('/')) {
+        throw new GithubPagesDeployError(`Invalid ${label}: "${value}".`);
+    }
+};
+const runGit = (args, cwd) => {
+    const result = spawnSync('git', args, {
+        cwd,
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            GIT_TERMINAL_PROMPT: '0',
+        },
+    });
+    if (result.error) {
+        throw new GithubPagesDeployError(`Failed to run git ${args.join(' ')}: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        const details = (result.stderr || result.stdout || '').trim();
+        throw new GithubPagesDeployError(`Git command failed: git ${args.join(' ')}${details ? `\n${details}` : ''}`);
+    }
+    return {
+        stderr: result.stderr.trim(),
+        stdout: result.stdout.trim(),
+    };
+};
+const getRemoteTrackingRef = (remote, branch) => `refs/remotes/${remote}/${branch}`;
+const fetchRemoteBranch = (repositoryRoot, remote, branch) => {
+    runGit(['fetch', remote, `+${branch}:${getRemoteTrackingRef(remote, branch)}`], repositoryRoot);
+};
+const remoteBranchExists = (repositoryRoot, remote, branch) => {
+    const result = spawnSync('git', ['ls-remote', '--exit-code', '--heads', remote, branch], {
+        cwd: repositoryRoot,
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            GIT_TERMINAL_PROMPT: '0',
+        },
+    });
+    if (result.error) {
+        throw new GithubPagesDeployError(`Failed to check ${remote}/${branch}: ${result.error.message}`);
+    }
+    if (result.status === 0) {
+        return true;
+    }
+    if (result.status === 2) {
+        return false;
+    }
+    const details = (result.stderr || result.stdout || '').trim();
+    throw new GithubPagesDeployError(`Git command failed: git ls-remote --exit-code --heads ${remote} ${branch}${details ? `\n${details}` : ''}`);
+};
+const getRepositoryRoot = (cwd) => {
+    try {
+        return runGit(['rev-parse', '--show-toplevel'], cwd).stdout;
+    }
+    catch {
+        throw new GithubPagesDeployError('Current directory must be inside a Git repository.');
+    }
+};
+const toGitPath = (path) => path.split(sep).join('/');
+const getBuildDirectoryPathspec = (repositoryRoot, buildDirectory) => {
+    const relativeBuildDirectory = relative(repositoryRoot, buildDirectory);
+    if (!relativeBuildDirectory || relativeBuildDirectory === '..' || relativeBuildDirectory.startsWith(`..${sep}`) || isAbsolute(relativeBuildDirectory)) {
+        throw new GithubPagesDeployError(`Build directory must be inside the repository: ${buildDirectory}`);
+    }
+    return toGitPath(relativeBuildDirectory);
+};
+const assertBuildDirectoryIsUntracked = (repositoryRoot, buildDirectoryPathspec, sourceBranch) => {
+    const trackedFiles = runGit(['ls-files', '--', buildDirectoryPathspec], repositoryRoot).stdout;
+    if (trackedFiles) {
+        throw new GithubPagesDeployError([
+            `Build directory "${buildDirectoryPathspec}" must not be tracked by Git.`,
+            `Remove it from ${sourceBranch} with: git rm -r --cached ${buildDirectoryPathspec}`,
+            `Keep "${buildDirectoryPathspec}/" ignored in .gitignore before deploying.`,
+        ].join('\n'));
+    }
+};
+const assertCleanWorkingTree = (repositoryRoot) => {
+    const status = runGit(['status', '--porcelain'], repositoryRoot).stdout;
+    if (status) {
+        throw new GithubPagesDeployError(`Working tree must be clean before deploying.\n${status}`);
+    }
+};
+const assertSyncedBranch = (repositoryRoot, sourceBranch, remote) => {
+    const currentBranch = runGit(['branch', '--show-current'], repositoryRoot).stdout;
+    if (currentBranch !== sourceBranch) {
+        throw new GithubPagesDeployError(`Current branch must be "${sourceBranch}". Found "${currentBranch || 'detached HEAD'}".`);
+    }
+    fetchRemoteBranch(repositoryRoot, remote, sourceBranch);
+    const localHead = runGit(['rev-parse', sourceBranch], repositoryRoot).stdout;
+    const remoteHead = runGit(['rev-parse', `${remote}/${sourceBranch}`], repositoryRoot).stdout;
+    if (localHead !== remoteHead) {
+        throw new GithubPagesDeployError(`${sourceBranch} must be synchronized with ${remote}/${sourceBranch} before deploying.`);
+    }
+};
+const assertBuildDirectory = async (buildDirectory) => {
+    let buildStat;
+    try {
+        buildStat = await stat(buildDirectory);
+    }
+    catch {
+        throw new GithubPagesDeployError(`Build directory does not exist: ${buildDirectory}`);
+    }
+    if (!buildStat.isDirectory()) {
+        throw new GithubPagesDeployError(`Build path must be a directory: ${buildDirectory}`);
+    }
+    const entries = await readdir(buildDirectory);
+    if (entries.length === 0) {
+        throw new GithubPagesDeployError(`Build directory is empty: ${buildDirectory}`);
+    }
+};
+const clearWorktree = async (worktreePath) => {
+    const entries = await readdir(worktreePath);
+    await Promise.all(entries
+        .filter((entry) => entry !== '.git')
+        .map((entry) => rm(join(worktreePath, entry), {
+        force: true,
+        recursive: true,
+    })));
+};
+const cleanupWorktree = async (repositoryRoot, worktreePath, tempRoot) => {
+    try {
+        runGit(['worktree', 'remove', '--force', worktreePath], repositoryRoot);
+    }
+    catch {
+        await rm(worktreePath, {
+            force: true,
+            recursive: true,
+        });
+    }
+    await rm(tempRoot, {
+        force: true,
+        recursive: true,
+    });
+};
+export const deployGithubPages = async (options = {}) => {
+    const resolved = resolveOptions(options);
+    assertSafeGitRefPart(resolved.sourceBranch, 'source branch');
+    assertSafeGitRefPart(resolved.remote, 'remote');
+    assertSafeGitRefPart(resolved.deploymentBranch, 'deployment branch');
+    const repositoryRoot = getRepositoryRoot(resolved.cwd);
+    const buildDirectory = resolve(repositoryRoot, resolved.buildDir);
+    const buildDirectoryPathspec = getBuildDirectoryPathspec(repositoryRoot, buildDirectory);
+    const deploymentRef = `${resolved.remote}/${resolved.deploymentBranch}`;
+    assertBuildDirectoryIsUntracked(repositoryRoot, buildDirectoryPathspec, resolved.sourceBranch);
+    assertCleanWorkingTree(repositoryRoot);
+    assertSyncedBranch(repositoryRoot, resolved.sourceBranch, resolved.remote);
+    const deploymentBranchExists = remoteBranchExists(repositoryRoot, resolved.remote, resolved.deploymentBranch);
+    if (deploymentBranchExists) {
+        fetchRemoteBranch(repositoryRoot, resolved.remote, resolved.deploymentBranch);
+    }
+    await assertBuildDirectory(buildDirectory);
+    const tempRoot = await mkdtemp(join(tmpdir(), 'micazoyolli-gh-pages-'));
+    const worktreePath = join(tempRoot, basename(repositoryRoot));
+    try {
+        runGit(['worktree', 'add', '--detach', worktreePath, deploymentBranchExists ? deploymentRef : resolved.sourceBranch], repositoryRoot);
+        if (!deploymentBranchExists) {
+            runGit(['checkout', '--orphan', resolved.deploymentBranch], worktreePath);
+        }
+        await clearWorktree(worktreePath);
+        await cp(buildDirectory, worktreePath, {
+            force: true,
+            recursive: true,
+        });
+        const deploymentStatus = runGit(['status', '--porcelain'], worktreePath).stdout;
+        if (!deploymentStatus) {
+            return {
+                deploymentBranch: resolved.deploymentBranch,
+                initialDeployment: false,
+                pushed: false,
+                reason: 'Deployment content is unchanged.',
+                remote: resolved.remote,
+                repositoryRoot,
+            };
+        }
+        runGit(['add', '--all'], worktreePath);
+        runGit(['commit', '-m', resolved.message], worktreePath);
+        const commit = runGit(['rev-parse', '--short', 'HEAD'], worktreePath).stdout;
+        runGit(['push', resolved.remote, `HEAD:${resolved.deploymentBranch}`], worktreePath);
+        fetchRemoteBranch(repositoryRoot, resolved.remote, resolved.deploymentBranch);
+        return {
+            commit,
+            deploymentBranch: resolved.deploymentBranch,
+            initialDeployment: !deploymentBranchExists,
+            pushed: true,
+            remote: resolved.remote,
+            repositoryRoot,
+        };
+    }
+    finally {
+        await cleanupWorktree(repositoryRoot, worktreePath, tempRoot);
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@micazoyolli/foundation",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "Fundamentos frontend no visuales para el ecosistema técnico de Nad.",
   "license": "MIT",
   "type": "module",
@@ -26,6 +26,9 @@
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "micazoyolli-gh-pages-deploy": "dist/cli/deploy-github-pages.js"
+  },
   "exports": {
     ".": {
       "import": "./dist/index.js",
@@ -42,16 +45,17 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json && yarn copy-scss",
+    "build": "tsc -p tsconfig.json && node scripts/mark-cli-executable.mjs && yarn copy-scss",
     "clean": "rm -rf dist",
     "copy-scss": "rsync -av --include='*/' --include='*.scss' --exclude='*' src/scss/ dist/scss/",
-    "docs:build": "vitepress build docs",
+    "docs:build": "yarn build && node scripts/generate-docs-seo.mjs && vitepress build docs",
     "docs:dev": "vitepress dev docs --host 0.0.0.0",
     "docs:preview": "vitepress preview docs --host 0.0.0.0",
     "prepack": "yarn build",
     "test": "yarn build && node --test tests/*.test.mjs"
   },
   "devDependencies": {
+    "@types/node": "24.10.4",
     "sass-embedded": "^1.100.0",
     "typescript": "6.0.3",
     "vitepress": "^1.6.4"