gemstack-ai 1.0.1

package/specs/v0.3-ci-cd/tasks.md

@@ -0,0 +1,98 @@
+# Tareas de Implementación: Gemstack v0.3 (CI/CD & Release Automation)
+
+Este documento contiene el plan de ejecución ejectuable (checklist) para el ciclo v0.3.
+
+---
+
+### Fase 0: Preflight
+- [ ] **T0.1: Asegurar Entorno Limpio**
+  - **Descripción:** Verificar con `git status` que no existan implementaciones previas, archivos colgados, etiquetas recién creadas ni subidas a NPM publicadas.
+  - **Archivos:** Ninguno
+  - **Criterio de Aceptación:** Working tree clean.
+  - **Riesgo:** Bajo.
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 1: `.gitattributes`
+- [ ] **T1.1: Estandarización de Line Endings**
+  - **Descripción:** Crear `.gitattributes` conservador para prevenir fallos de SHA-256 cross-platform. Ejecutar `git status` y pausar si se normaliza excesivamente.
+  - **Archivos:** `.gitattributes`
+  - **Criterio de Aceptación:** Archivo creado. El Churn de EOL no debe romper archivos binarios.
+  - **Riesgo:** Alto (Normalización masiva o corrupción de binarios si las reglas son muy globales).
+  - **Requiere Aprobación Humana:** **SÍ** (Si `git status` muestra más de 10 archivos modificados únicamente por EOL).
+
+### Fase 2: `scripts/ci/`
+- [ ] **T2.1: Validadores Nativos Zero-Deps**
+  - **Descripción:** Implementar validadores de calidad.
+    1. `check-frontmatter.js`: Revisa formato YAML en `.agents/skills/*/SKILL.md`.
+    2. `check-template-clean.js`: Revisa ausencia de contexto privado y secretos en `template/`.
+    3. `check-mojibake.js`: Busca caracteres rotos en UTF-8 (ej: `Ã`).
+    4. `check-package-contents.js`: Realiza inspección tras `npm pack --dry-run`.
+    5. `smoke-cli.js`: Prueba programática (e2e) en directorios temporales de todas las ramas del CLI (`help`, `doctor`, `init`, `update`).
+  - **Archivos:** `scripts/ci/*.js`
+  - **Criterio de Aceptación:** Cross-platform (Win/Mac/Linux), cero dependencias externas de npm.
+  - **Riesgo:** Moderado (Incompatibilidad en spawns de child processes en Windows vs Unix).
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 3: Package Scripts
+- [ ] **T3.1: Configuración de npm run alias**
+  - **Descripción:** Extender el bloque `scripts` en `package.json` insertando `ci:frontmatter`, `ci:template`, `ci:mojibake`, `ci:package`, `ci:smoke` y un atajo `ci:all`.
+  - **Archivos:** `package.json`
+  - **Criterio de Aceptación:** Ejecutar `npm run ci:all` lanza secuencialmente la batería de checks.
+  - **Riesgo:** Bajo.
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 4: Workflow `pr-ci.yml`
+- [ ] **T4.1: CI Eficiente para Pull Requests**
+  - **Descripción:** Workflow rápido basado en Ubuntu con Matrix en Node 18 y 20. Ejecuta las validaciones `ci:all`, `npm test` y el smoke test de la `demo-app`.
+  - **Archivos:** `.github/workflows/pr-ci.yml`
+  - **Criterio de Aceptación:** El YAML es sintácticamente válido para Actions y optimiza el uso de CPU.
+  - **Riesgo:** Bajo.
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 5: Workflow `main-ci.yml`
+- [ ] **T5.1: CI Exhaustivo para la Rama Principal**
+  - **Descripción:** Se lanza tras merges y pushes a `main`. Emplea una Matrix completa (Windows, macOS, Ubuntu) en Node 18 y 20.
+  - **Archivos:** `.github/workflows/main-ci.yml`
+  - **Criterio de Aceptación:** Todos los tests y utilidades CI se mapean multiplataforma de forma estricta.
+  - **Riesgo:** Medio (Desviación en OS, comandos bash que fallen en el runner de Windows).
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 6: Workflow `release-readiness.yml`
+- [ ] **T6.1: Generación y Validación de Tarball Manual**
+  - **Descripción:** Trigger exclusivo `workflow_dispatch`. Realiza un test cross-platform donde genera un `.tgz`, levanta un proyecto vacío en otra carpeta temporal, lo instala con NPM y realiza comprobaciones unitarias `npx gemstack` reales de punta a punta. Sube el `.tgz` como artefacto final.
+  - **Archivos:** `.github/workflows/release-readiness.yml`
+  - **Criterio de Aceptación:** NO efectúa tags, NPM publish, ni GitHub Releases automáticamente.
+  - **Riesgo:** Medio (Estructura de logs pesada o fallo en instalación del paquete local del tarball).
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 7: Documentación
+- [ ] **T7.1: Badge CI y Notas**
+  - **Descripción:** Agregar badge de CI a la cabecera de `README.md`. Preparar borrador de notas en `RELEASE_NOTES.md` o `CHANGELOG.md` describiendo la infraestructura CI.
+  - **Archivos:** `README.md`, `CHANGELOG.md`, `docs/release.md`
+  - **Criterio de Aceptación:** Información asertiva y documentada.
+  - **Riesgo:** Bajo.
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 8: Validación Local
+- [ ] **T8.1: Prueba del Suite Completo Local**
+  - **Descripción:** Correr `npm test`, `npm run ci:all`, comprobar si `demo-app` no sufre regresiones.
+  - **Archivos:** Ninguno.
+  - **Criterio de Aceptación:** Todos los scripts retornan un exit code `0`. Sin archivos `temp` huérfanos residuales.
+  - **Riesgo:** Medio (Tiempos de ejecución o errores no controlados si fallan limpiezas `tmp`).
+  - **Requiere Aprobación Humana:** **SÍ** (Aprobación si se detectan anomalías de basura en disco).
+
+### Fase 9: Revisión de Seguridad y QA Agentic
+- [ ] **T9.1: Emulación de Audits `/review` y `/cso`**
+  - **Descripción:** Evaluar los workflows implementados contra vulnerabilidades (Supply Chain, Secret Leaks, Privilegios del GITHUB_TOKEN). Actualizar los docs.
+  - **Archivos:** `docs/reviews/latest-review.md`, `docs/security/latest-security-audit.md`
+  - **Criterio de Aceptación:** Análisis honesto registrando deficiencias o limitantes de la CI.
+  - **Riesgo:** Bajo.
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 10: Commit, Push y Handoff
+- [ ] **T10.1: Integración Final**
+  - **Descripción:** Confirmar árbol limpio mediante `git status -u`. Efectuar commit, push e incorporar memoria al `handoff.md`. Push final.
+  - **Archivos:** `handoff.md`
+  - **Criterio de Aceptación:** Sin rastros de builds. Versionado estable listo para activar en GitHub Actions.
+  - **Riesgo:** Bajo.
+  - **Requiere Aprobación Humana:** **SÍ** (Confirmar antes de commit y push).

package/src/cli.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+const parser = require('./lib/parser');
+const logger = require('./lib/logger');
+const initCommand = require('./commands/init');
+const updateCommand = require('./commands/update');
+const doctorCommand = require('./commands/doctor');
+const listCommand = require('./commands/list');
+const showCommand = require('./commands/show');
+const hooksCommand = require('./commands/hooks');
+const installCommand = require('./commands/install');
+
+async function main() {
+    const { command, args, flags } = parser.parse(process.argv);
+
+    if (flags.help || command === 'help') {
+        console.log(`Gemstack CLI
+Commands:
+  init      Install Gemstack scaffolding
+  update    Update Gemstack-owned files
+  doctor    Check health of the installation
+  list      List available skills
+  show      Show content of a skill
+  handoff   Show content of handoff.md
+  hooks     Install native Git pre-commit hooks for active security
+  install   Install a remote skill via URL
+  mcp       Start the Gemstack MCP (Model Context Protocol) server over stdio
+Options:
+  --dry-run Show changes without writing
+  --yes     Skip confirmations
+  --force   Force overwrite (update only)
+  --target  Specify target directory`);
+        return;
+    }
+
+    try {
+        switch (command) {
+            case 'init': await initCommand(flags); break;
+            case 'update': await updateCommand(flags); break;
+            case 'doctor': await doctorCommand(flags); break;
+            case 'list': await listCommand(flags); break;
+            case 'show': await showCommand(args[0], flags); break;
+            case 'hooks': hooksCommand.installHooks(flags.target); break;
+            case 'install': await installCommand(args[0], flags); break;
+            case 'mcp': require('./mcp-server'); break;
+            case 'handoff': {
+                const fs = require('fs');
+                const path = require('path');
+                const fssafe = require('./lib/filesystem-safe');
+                const p = fssafe.resolveSafe(flags.target, 'handoff.md');
+                if (fs.existsSync(p)) console.log(fs.readFileSync(p, 'utf8'));
+                else logger.error('handoff.md not found');
+                break;
+            }
+            default:
+                logger.error(`Unknown command: ${command}`);
+                process.exit(1);
+        }
+    } catch (e) {
+        logger.error(e.message);
+        process.exit(1);
+    }
+}
+
+main();

package/src/commands/doctor.js

@@ -0,0 +1,50 @@
+const fs = require('fs');
+const fssafe = require('../lib/filesystem-safe');
+const logger = require('../lib/logger');
+
+module.exports = async (flags) => {
+    const targetDir = flags.target;
+    logger.info(`Running doctor on ${targetDir}`);
+    
+    const manifestPath = fssafe.resolveSafe(targetDir, '.gemstack/manifest.json');
+    if (!fs.existsSync(manifestPath)) {
+        logger.error('Manifest not found. Gemstack is not initialized here.');
+        process.exit(1);
+    }
+    
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    logger.ok(`Manifest version: ${manifest.version}`);
+    
+    let missing = 0;
+    let modified = 0;
+    const manifestLib = require('../lib/manifest');
+
+    (manifest.files || []).forEach(f => {
+        const p = fssafe.resolveSafe(targetDir, f.path);
+        if (!fs.existsSync(p)) {
+            logger.error(`Missing owned file: ${f.path}`);
+            missing++;
+        } else {
+            const destContent = fs.readFileSync(p);
+            const destCheck = manifestLib.getChecksum(destContent);
+            if (destCheck !== f.checksum) {
+                logger.warn(`Modified owned file: ${f.path}`);
+                modified++;
+            }
+        }
+    });
+
+    if (missing === 0 && modified === 0) {
+        logger.ok('All owned files are present and unmodified.');
+    } else {
+        logger.info(`Summary: ${missing} missing, ${modified} modified. Use 'gemstack update' if you want to restore defaults.`);
+    }
+
+    const giPath = fssafe.resolveSafe(targetDir, '.gitignore');
+    if (fs.existsSync(giPath) && fs.readFileSync(giPath, 'utf8').includes('# Gemstack')) {
+        logger.ok('.gitignore is patched.');
+    } else {
+        logger.warn('.gitignore is not patched.');
+    }
+    logger.ok('Doctor checks completed.');
+};

package/src/commands/hooks.js

@@ -0,0 +1,67 @@
+const fs = require('fs');
+const path = require('path');
+const logger = require('../lib/logger');
+
+const PRE_COMMIT_HOOK = `#!/bin/sh
+# Gemstack - Git Pre-commit Hook
+# Este hook previene que subas secretos o rompas la Ley de Seguridad (Rule 03).
+
+echo "[Gemstack] Ejecutando análisis de seguridad local..."
+
+# 1. Evitar que se suban archivos .env
+if git diff --cached --name-only | grep -E "^\\.env|\\.env\\.local|\\.env\\.production" > /dev/null; then
+    echo "❌ ERROR (Gemstack): Estás intentando hacer commit de un archivo .env"
+    echo "Regla 03: Gestión de Secretos. Remuévelo usando 'git reset HEAD <archivo>' y añádelo al .gitignore."
+    exit 1
+fi
+
+# 2. Buscar marcadores de conflicto de merge olvidados
+if git diff --cached -S"<<<<<<< HEAD" --quiet; then
+    # -quiet retorna 0 si encuentra coincidencias (no output)
+    :
+else
+    # Si git diff encuenta "<<<<<<<"
+    if git diff --cached | grep -E "^\\+<<<<<<<" > /dev/null; then
+        echo "❌ ERROR (Gemstack): Hay marcadores de conflicto de git (<<<<<<<) en tus archivos."
+        echo "Resuélvelos antes de hacer commit."
+        exit 1
+    fi
+fi
+
+# 3. Buscar posibles llaves expuestas (Stripe, AWS, JWT genéricos) en código agregado
+# Extrae las líneas añadidas y busca patrones peligrosos
+if git diff --cached | grep -E "^\\+.*(sk_live_|sk_test_|AKIA[0-9A-Z]{16}|xoxb-|ghp_)" > /dev/null; then
+    echo "❌ ERROR (Gemstack/CSO): ¡Posible llave secreta detectada en el código!"
+    echo "Regla 03: Cero Exposición de Credenciales. Extrae el secreto a una variable de entorno."
+    exit 1
+fi
+
+echo "✅ [Gemstack] Código limpio. Committing..."
+exit 0
+`;
+
+function installHooks(targetDir) {
+    const gitDir = path.join(targetDir, '.git');
+    const hooksDir = path.join(gitDir, 'hooks');
+    const preCommitPath = path.join(hooksDir, 'pre-commit');
+
+    if (!fs.existsSync(gitDir)) {
+        logger.info('No se detectó un repositorio git. Omitiendo instalación de hooks.');
+        return false;
+    }
+
+    try {
+        if (!fs.existsSync(hooksDir)) {
+            fs.mkdirSync(hooksDir, { recursive: true });
+        }
+
+        fs.writeFileSync(preCommitPath, PRE_COMMIT_HOOK, { mode: 0o755 });
+        logger.ok('Git hooks (pre-commit) instalados exitosamente.');
+        return true;
+    } catch (err) {
+        logger.error(`Error instalando git hooks: ${err.message}`);
+        return false;
+    }
+}
+
+module.exports = { installHooks };

package/src/commands/init.js

@@ -0,0 +1,90 @@
+const fs = require('fs');
+const path = require('path');
+const fssafe = require('../lib/filesystem-safe');
+const logger = require('../lib/logger');
+const manifestLib = require('../lib/manifest');
+const backupLib = require('../lib/backup');
+const gitignoreLib = require('../lib/gitignore');
+const hooks = require('./hooks');
+
+function walkDir(dir, callback) {
+    fs.readdirSync(dir).forEach(f => {
+        const dirPath = path.join(dir, f);
+        if (fs.statSync(dirPath).isDirectory()) walkDir(dirPath, callback);
+        else callback(dirPath);
+    });
+}
+
+module.exports = async (flags) => {
+    const targetDir = flags.target;
+    const templateDir = path.resolve(__dirname, '../../template');
+    if (!fs.existsSync(templateDir)) {
+        throw new Error('Template directory missing in Gemstack installation.');
+    }
+
+    logger.info(`Running init on ${targetDir}`);
+    const manifest = manifestLib.loadManifest(targetDir);
+    if (!manifest.files) manifest.files = [];
+    
+    let conflicts = [];
+    let toCopy = [];
+
+    walkDir(templateDir, (filePath) => {
+        const relativePath = path.relative(templateDir, filePath).replace(/\\/g, '/');
+        const destPath = fssafe.resolveSafe(targetDir, relativePath);
+
+        if (fs.existsSync(destPath)) {
+            if (['handoff.md', 'handoff_archive.md', '.gemstack/learnings.md', '.gemstack/state.json'].includes(relativePath)) {
+                // Safe ignore
+            } else {
+                conflicts.push(relativePath);
+            }
+        } else {
+            toCopy.push(relativePath);
+        }
+    });
+
+    if (flags.dryRun) {
+        logger.ok(`Dry run: Will create ${toCopy.length} files.`);
+        if (conflicts.length > 0) logger.warn(`Conflicts found in ${conflicts.length} files. Requires --yes to backup & overwrite.`);
+        return;
+    }
+
+    if (conflicts.length > 0 && !flags.yes) {
+        logger.error(`Conflicts detected in ${conflicts.length} files. Aborting.`);
+        logger.info(`Run with --yes to backup and overwrite Gemstack-owned files, or --dry-run to inspect.`);
+        process.exit(1);
+    }
+
+    const sessionTimestamp = new Date().toISOString().replace(/[:.]/g, '-');
+
+    if (flags.yes) {
+        for (const rel of conflicts) {
+            backupLib.backupFile(targetDir, rel, flags.dryRun, sessionTimestamp);
+            toCopy.push(rel);
+        }
+    }
+
+    for (const rel of toCopy) {
+        const src = path.join(templateDir, rel);
+        const dest = fssafe.resolveSafe(targetDir, rel);
+        fssafe.ensureDir(path.dirname(dest));
+        fs.copyFileSync(src, dest);
+        logger.ok(`Created ${rel}`);
+        
+        const content = fs.readFileSync(dest);
+        const ex = manifest.files.find(f => f.path === rel);
+        if (ex) ex.checksum = manifestLib.getChecksum(content);
+        else manifest.files.push({ path: rel, checksum: manifestLib.getChecksum(content) });
+    }
+
+    gitignoreLib.patchGitignore(targetDir, flags.dryRun);
+    manifestLib.saveManifest(targetDir, manifest, flags.dryRun);
+    
+    // Attempt to install native Git hooks
+    if (!flags.dryRun) {
+        hooks.installHooks(targetDir);
+    }
+
+    logger.ok('Gemstack initialization complete.');
+};

package/src/commands/install.js

@@ -0,0 +1,72 @@
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const fssafe = require('../lib/filesystem-safe');
+const logger = require('../lib/logger');
+const manifestLib = require('../lib/manifest');
+
+async function fetchUrl(url) {
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch: ${response.status} ${response.statusText}`);
+    }
+    return await response.text();
+}
+
+function extractSkillName(content) {
+    const match = content.match(/^name:\s*(.+)$/m);
+    return match ? match[1].trim() : null;
+}
+
+module.exports = async (url, flags) => {
+    if (!url) {
+        logger.error("Debe proporcionar una URL. Ejemplo: gemstack install https://raw.githubusercontent.com/.../SKILL.md");
+        process.exit(1);
+    }
+
+    const targetDir = flags.target || process.cwd();
+    logger.info(`Descargando skill desde: ${url}`);
+
+    try {
+        const content = await fetchUrl(url);
+        
+        // Ensure it's a valid skill file
+        if (!content.includes('---')) {
+            throw new Error('El archivo descargado no parece un SKILL válido (no tiene frontmatter).');
+        }
+
+        const skillName = extractSkillName(content);
+        if (!skillName) {
+            throw new Error('No se encontró "name: <nombre>" en el frontmatter del SKILL.');
+        }
+
+        // Calculate path
+        const relativePath = `.agents/skills/${skillName}/SKILL.md`;
+        const destPath = fssafe.resolveSafe(targetDir, relativePath);
+
+        if (flags.dryRun) {
+            logger.ok(`Dry run: Se instalaría el skill "${skillName}" en ${relativePath}`);
+            return;
+        }
+
+        // Install the skill
+        fssafe.ensureDir(path.dirname(destPath));
+        fs.writeFileSync(destPath, content, 'utf8');
+
+        // Update manifest
+        const manifest = manifestLib.loadManifest(targetDir);
+        if (!manifest.files) manifest.files = [];
+        
+        const checksum = manifestLib.getChecksum(Buffer.from(content, 'utf8'));
+        const ex = manifest.files.find(f => f.path === relativePath);
+        if (ex) ex.checksum = checksum;
+        else manifest.files.push({ path: relativePath, checksum });
+        
+        manifestLib.saveManifest(targetDir, manifest, false);
+
+        logger.ok(`✅ Skill "${skillName}" instalado exitosamente en ${relativePath}`);
+    } catch (e) {
+        logger.error(`Error instalando el skill: ${e.message}`);
+        process.exit(1);
+    }
+};

package/src/commands/list.js

@@ -0,0 +1,20 @@
+const fs = require('fs');
+const fssafe = require('../lib/filesystem-safe');
+const logger = require('../lib/logger');
+
+module.exports = async (flags) => {
+    const targetDir = flags.target;
+    const skillsDir = fssafe.resolveSafe(targetDir, '.agents/skills');
+    
+    if (!fs.existsSync(skillsDir)) {
+        logger.error(`No skills directory found at ${skillsDir}`);
+        return;
+    }
+    
+    logger.info('Installed Skills:');
+    fs.readdirSync(skillsDir).forEach(dir => {
+        if (dir.startsWith('gemstack-')) {
+            logger.ok(dir);
+        }
+    });
+};

package/src/commands/show.js

@@ -0,0 +1,18 @@
+const fs = require('fs');
+const fssafe = require('../lib/filesystem-safe');
+const logger = require('../lib/logger');
+
+module.exports = async (skill, flags) => {
+    if (!skill) {
+        logger.error('Must provide skill name');
+        process.exit(1);
+    }
+    const targetDir = flags.target;
+    const p = fssafe.resolveSafe(targetDir, `.agents/skills/${skill}/SKILL.md`);
+    
+    if (!fs.existsSync(p)) {
+        logger.error(`Skill ${skill} not found at ${p}`);
+        return;
+    }
+    console.log(fs.readFileSync(p, 'utf8'));
+};

package/src/commands/update.js

@@ -0,0 +1,88 @@
+const fs = require('fs');
+const path = require('path');
+const fssafe = require('../lib/filesystem-safe');
+const logger = require('../lib/logger');
+const manifestLib = require('../lib/manifest');
+const backupLib = require('../lib/backup');
+
+function walkDir(dir, callback) {
+    fs.readdirSync(dir).forEach(f => {
+        const dirPath = path.join(dir, f);
+        if (fs.statSync(dirPath).isDirectory()) walkDir(dirPath, callback);
+        else callback(dirPath);
+    });
+}
+
+module.exports = async (flags) => {
+    const targetDir = flags.target;
+    const templateDir = path.resolve(__dirname, '../../template');
+    
+    logger.info(`Running update on ${targetDir}`);
+    const manifest = manifestLib.loadManifest(targetDir);
+    if (!manifest.files) manifest.files = [];
+    let toUpdate = [];
+
+    walkDir(templateDir, (filePath) => {
+        const relativePath = path.relative(templateDir, filePath).replace(/\\/g, '/');
+        const destPath = fssafe.resolveSafe(targetDir, relativePath);
+        
+        const tmplContent = fs.readFileSync(filePath);
+        const tmplCheck = manifestLib.getChecksum(tmplContent);
+        
+        const exManifest = manifest.files.find(f => f.path === relativePath);
+
+        if (fs.existsSync(destPath)) {
+            const destContent = fs.readFileSync(destPath);
+            const destCheck = manifestLib.getChecksum(destContent);
+            
+            if (exManifest && destCheck !== exManifest.checksum && destCheck !== tmplCheck) {
+                if (!flags.force) {
+                    logger.warn(`User modified ${relativePath}. Skipping. Use --force to override.`);
+                    return;
+                }
+            }
+            if (tmplCheck !== destCheck) {
+                toUpdate.push(relativePath);
+            }
+        } else {
+            // File exists in template but not in target (new skill/file)
+            toUpdate.push(relativePath);
+        }
+    });
+
+    if (toUpdate.length === 0) {
+        logger.ok('Everything is up to date.');
+        return;
+    }
+
+    if (flags.dryRun) {
+        logger.ok(`Dry run: Will update ${toUpdate.length} files.`);
+        toUpdate.forEach(f => logger.info(` -> ${f}`));
+        return;
+    }
+
+    if (!flags.yes) {
+        logger.error(`Updates available for ${toUpdate.length} files. Aborting.`);
+        logger.info(`Run with --yes to backup and apply updates.`);
+        process.exit(1);
+    }
+
+    const sessionTimestamp = new Date().toISOString().replace(/[:.]/g, '-');
+
+    for (const rel of toUpdate) {
+        backupLib.backupFile(targetDir, rel, flags.dryRun, sessionTimestamp);
+        const src = path.join(templateDir, rel);
+        const dest = fssafe.resolveSafe(targetDir, rel);
+        fssafe.ensureDir(path.dirname(dest));
+        fs.copyFileSync(src, dest);
+        logger.ok(`Updated ${rel}`);
+        
+        const ex = manifest.files.find(f => f.path === rel);
+        const newChecksum = manifestLib.getChecksum(fs.readFileSync(dest));
+        if (ex) ex.checksum = newChecksum;
+        else manifest.files.push({ path: rel, checksum: newChecksum });
+    }
+
+    manifestLib.saveManifest(targetDir, manifest, flags.dryRun);
+    logger.ok('Gemstack update complete.');
+};

package/src/lib/backup.js

@@ -0,0 +1,29 @@
+const fs = require('fs');
+const path = require('path');
+const fssafe = require('./filesystem-safe');
+const logger = require('./logger');
+
+module.exports = {
+    backupFile: (targetDir, relativeFilePath, dryRun, sessionTimestamp) => {
+        const fullPath = fssafe.resolveSafe(targetDir, relativeFilePath);
+        if (!fs.existsSync(fullPath)) return;
+
+        const timestamp = sessionTimestamp || new Date().toISOString().replace(/[:.]/g, '-');
+        const backupDir = fssafe.resolveSafe(targetDir, `.gemstack/backups/${timestamp}`);
+        const backupDest = fssafe.resolveSafe(backupDir, relativeFilePath);
+
+        logger.info(`Backup: ${relativeFilePath}`);
+        if (!dryRun) {
+            fssafe.ensureDir(path.dirname(backupDest));
+            fs.copyFileSync(fullPath, backupDest);
+            
+            const manifestPath = path.join(backupDir, 'manifest.json');
+            let manifest = [];
+            if (fs.existsSync(manifestPath)) {
+                manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+            }
+            manifest.push({ original: relativeFilePath, backup: backupDest, timestamp });
+            fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+        }
+    }
+};

package/src/lib/filesystem-safe.js

@@ -0,0 +1,22 @@
+const path = require('path');
+const fs = require('fs');
+
+module.exports = {
+    resolveSafe: (targetDir, relativePath) => {
+        const target = path.resolve(targetDir);
+        const candidate = path.resolve(targetDir, relativePath);
+        const rel = path.relative(target, candidate);
+        
+        const isInside = rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+        
+        if (!isInside) {
+            throw new Error(`Path Traversal blocked: ${relativePath}`);
+        }
+        return candidate;
+    },
+    ensureDir: (dirPath) => {
+        if (!fs.existsSync(dirPath)) {
+            fs.mkdirSync(dirPath, { recursive: true });
+        }
+    }
+};

package/src/lib/gitignore.js

@@ -0,0 +1,19 @@
+const fs = require('fs');
+const fssafe = require('./filesystem-safe');
+const logger = require('./logger');
+
+module.exports = {
+    patchGitignore: (targetDir, dryRun) => {
+        const giPath = fssafe.resolveSafe(targetDir, '.gitignore');
+        let content = fs.existsSync(giPath) ? fs.readFileSync(giPath, 'utf8') : '';
+        if (content.includes('# Gemstack')) {
+            return;
+        }
+        
+        const block = `\n# Gemstack\n.gemstack/state.json\n.gemstack/backups/\n`;
+        logger.info(`Patching .gitignore`);
+        if (!dryRun) {
+            fs.appendFileSync(giPath, block);
+        }
+    }
+};

package/src/lib/logger.js

@@ -0,0 +1,6 @@
+module.exports = {
+    info: (msg) => console.log(`[INFO] ${msg}`),
+    ok: (msg) => console.log(`[OK] ${msg}`),
+    error: (msg) => console.error(`[FAIL] ${msg}`),
+    warn: (msg) => console.warn(`[WARN] ${msg}`)
+};