update-base-config 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# update-base-config
+
+`update-base-config` is a small `npx` CLI that copies shared project-local AI agent skills from this repository into another repository.
+
+## What it syncs
+
+The CLI copies each skill from `templates/skills/` into `.agents/skills/`, `.claude/skills/`, `.opencode/skills/`, and `.codex/skills/`.
+
+## Behavior
+
+- Shows a summary before changing files
+- Asks for confirmation by default
+- Creates a backup before replacing an existing skill file
+
+Backups are stored inside the target project under `.update-base-config-backups/<timestamp>/`.
+
+## Usage
+
+```bash
+npx update-base-config
+npx update-base-config --dry-run
+npx update-base-config --yes
+```
+
+## Develop the template
+
+Edit every shared skill once inside `templates/skills/`. The CLI distributes that master source into each supported local agent directory.

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "update-base-config",
+  "version": "0.1.0",
+  "description": "Install and update shared AI agent project configuration from a fixed template.",
+  "type": "module",
+  "bin": {
+    "update-base-config": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "license": "MIT"
+}

package/src/index.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+
+import path from 'node:path';
+import process from 'node:process';
+import { access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import readline from 'node:readline/promises';
+import {
+  applyOperations,
+  buildBackupRoot,
+  formatSummary,
+  getDefaultSkillsRoot,
+  planSync,
+  summarizeOperations
+} from './lib.js';
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  const targetRoot = path.resolve(args.targetRoot ?? process.cwd());
+  const skillsRoot = path.resolve(args.skillsRoot ?? getDefaultSkillsRoot());
+
+  await ensureReadableDirectory(skillsRoot, 'skills template');
+  await ensureReadableDirectory(targetRoot, 'target');
+
+  const operations = await planSync({ skillsRoot, targetRoot });
+  const actionable = operations.filter((operation) => operation.type !== 'skip');
+
+  console.log(formatSummary(operations, targetRoot));
+
+  if (actionable.length === 0) {
+    console.log('\nNo changes required.');
+    return;
+  }
+
+  if (args.dryRun) {
+    console.log('\nDry run only. No files were modified.');
+    return;
+  }
+
+  if (!args.yes) {
+    const confirmed = await askForConfirmation();
+    if (!confirmed) {
+      console.log('Cancelled.');
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  const backupRoot = buildBackupRoot(targetRoot);
+  const result = await applyOperations({ operations, backupRoot });
+  const summary = summarizeOperations(operations);
+
+  console.log('');
+  console.log(`Applied ${summary.create + summary.merge + summary.replace} changes.`);
+  if (result.backupCreated) {
+    console.log(`Backups saved in ${backupRoot}`);
+  }
+}
+
+function parseArgs(argv) {
+  const args = {
+    yes: false,
+    dryRun: false,
+    help: false,
+    targetRoot: null,
+    skillsRoot: null
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (token === '--yes' || token === '-y') {
+      args.yes = true;
+      continue;
+    }
+
+    if (token === '--dry-run') {
+      args.dryRun = true;
+      continue;
+    }
+
+    if (token === '--help' || token === '-h') {
+      args.help = true;
+      continue;
+    }
+
+    if (token === '--target') {
+      args.targetRoot = argv[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (token === '--skills-root') {
+      args.skillsRoot = argv[index + 1];
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${token}`);
+  }
+
+  return args;
+}
+
+function printHelp() {
+  console.log(`update-base-config
+
+Usage:
+  npx update-base-config
+  npx update-base-config --dry-run
+  npx update-base-config --yes
+
+Options:
+  --yes, -y         Apply without asking for confirmation
+  --dry-run         Show the plan without writing files
+  --target <path>   Override the target project directory
+  --skills-root     Override the master skills directory
+  --help, -h        Show this message
+`);
+}
+
+async function ensureReadableDirectory(directoryPath, label) {
+  try {
+    await access(directoryPath, constants.R_OK);
+  } catch {
+    throw new Error(`Cannot read ${label} directory: ${directoryPath}`);
+  }
+}
+
+async function askForConfirmation() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  try {
+    const answer = await rl.question('\nApply these changes? (y/N) ');
+    return answer.trim().toLowerCase() === 'y';
+  } finally {
+    rl.close();
+  }
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/src/lib.js

@@ -0,0 +1,144 @@
+import path from 'node:path';
+import { mkdir, readFile, readdir, stat, writeFile, copyFile } from 'node:fs/promises';
+
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export function getDefaultSkillsRoot() {
+  return path.resolve(__dirname, '..', 'templates', 'skills');
+}
+
+export async function collectFiles(rootDir) {
+  const entries = await readdir(rootDir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    if (entry.name === '.DS_Store') {
+      continue;
+    }
+
+    const absolutePath = path.join(rootDir, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...(await collectFiles(absolutePath)));
+      continue;
+    }
+
+    if (entry.isFile()) {
+      files.push(absolutePath);
+    }
+  }
+
+  return files.sort();
+}
+
+export async function planSync({ skillsRoot, targetRoot }) {
+  const skillFiles = await collectFiles(skillsRoot);
+  const operations = [];
+
+  for (const sourcePath of skillFiles) {
+    const skillPath = path.relative(skillsRoot, sourcePath);
+
+    for (const agentRoot of ['.agents', '.claude', '.opencode', '.codex']) {
+      const relativePath = path.join(agentRoot, 'skills', skillPath);
+      operations.push(...(await planFile({ sourcePath, relativePath, targetRoot })));
+    }
+  }
+
+  return operations;
+}
+
+async function planFile({ sourcePath, relativePath, targetRoot }) {
+  const targetPath = path.join(targetRoot, relativePath);
+  const targetInfo = await readExistingFile(targetPath);
+  const sourceContent = await readFile(sourcePath, 'utf8');
+
+  if (!targetInfo.exists) {
+    return [{ type: 'create', relativePath, sourcePath, targetPath, content: sourceContent }];
+  }
+
+  if (targetInfo.content === sourceContent) {
+    return [{ type: 'skip', relativePath, sourcePath, targetPath, reason: 'already up to date' }];
+  }
+
+  return [{ type: 'replace', relativePath, sourcePath, targetPath, content: sourceContent }];
+}
+
+async function readExistingFile(filePath) {
+  try {
+    const fileStat = await stat(filePath);
+    if (!fileStat.isFile()) {
+      return { exists: false, content: null };
+    }
+
+    return {
+      exists: true,
+      content: await readFile(filePath, 'utf8')
+    };
+  } catch {
+    return { exists: false, content: null };
+  }
+}
+
+export function summarizeOperations(operations) {
+  return operations.reduce(
+    (summary, operation) => {
+      summary[operation.type] = (summary[operation.type] ?? 0) + 1;
+      return summary;
+    },
+    { create: 0, merge: 0, replace: 0, skip: 0 }
+  );
+}
+
+export function formatSummary(operations, targetRoot) {
+  const summary = summarizeOperations(operations);
+  const lines = [
+    `Target: ${targetRoot}`,
+    `Create: ${summary.create}`,
+    `Merge: ${summary.merge}`,
+    `Replace with backup: ${summary.replace}`,
+    `Skip: ${summary.skip}`,
+    '',
+    'Planned changes:'
+  ];
+
+  for (const operation of operations) {
+    if (operation.type === 'skip') {
+      continue;
+    }
+
+    const detail = operation.type === 'merge' ? ` (${operation.mergeKind})` : '';
+    lines.push(`- ${operation.type.toUpperCase()} ${operation.relativePath}${detail}`);
+  }
+
+  return lines.join('\n');
+}
+
+export async function applyOperations({ operations, backupRoot }) {
+  let backupCreated = false;
+
+  for (const operation of operations) {
+    if (operation.type === 'skip') {
+      continue;
+    }
+
+    await mkdir(path.dirname(operation.targetPath), { recursive: true });
+
+    if (operation.type === 'replace') {
+      const backupPath = path.join(backupRoot, operation.relativePath);
+      await mkdir(path.dirname(backupPath), { recursive: true });
+      await copyFile(operation.targetPath, backupPath);
+      backupCreated = true;
+    }
+
+    await writeFile(operation.targetPath, operation.content, 'utf8');
+  }
+
+  return { backupCreated };
+}
+
+export function buildBackupRoot(targetRoot, now = new Date()) {
+  const timestamp = now.toISOString().replace(/[:.]/g, '-');
+  return path.join(targetRoot, '.update-base-config-backups', timestamp);
+}

package/templates/skills/ids/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: ids
+description: Gestiona y valida IDs en elementos interactivos del proyecto m-personas con formato estándar para analytics y calidad.
+license: MIT
+metadata:
+    author: m-personas
+    version: "1.0"
+---
+
+# Skill: Gestión de IDs
+
+Usa esta skill cuando necesites:
+
+- Detectar elementos interactivos sin `id`
+- Corregir IDs con formato inválido
+- Aplicar auto-fix de ESLint para IDs
+- Revisar el estándar `[PREFIX]_landing-[TIPO]-[CONTEXTO]`
+
+## Documentación
+
+- Inicio rápido: [docs/SKILL_QUICK_START.md](./docs/SKILL_QUICK_START.md)
+- Guía general: [docs/SKILL_README.md](./docs/SKILL_README.md)
+- Guía técnica: [docs/SKILL_ID_MANAGEMENT.md](./docs/SKILL_ID_MANAGEMENT.md)
+- Resumen visual: [docs/SKILL_INICIO.txt](./docs/SKILL_INICIO.txt)
+
+## Comandos útiles
+
+- `npx eslint --fix src/`
+- `node scripts/manageIds.js --analyze src/pages`
+- `node scripts/manageIds.js --report`
+
+## Notas de proyecto
+
+- Prefijo esperado por defecto: `ppp_` (Banco Chile)
+- En Banco Edwards: `pbec_`
+- La validación es warning en desarrollo y error en producción
+
+## Cómo resolverlo
+
+Usa ids con el formato `[PREFIX]_[SECCION]-[TIPO]-[CONTEXTO]`, donde `[SECCION]` puede ser `landing`, `header` o `footer`; `link` para `<a>` y `btn` para `<button>`.