ppcos 1.0.0 → 1.0.2

package/bin/ppcos.js

@@ -25,10 +25,12 @@ const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8
  */
 function gated(fn) {
   return async (...args) => {
-    const auth = requireAuth();
-    if (!auth) {
-      process.exitCode = 1;
-      return;
+    if (!process.env.PPCOS_DEV) {
+      const auth = requireAuth();
+      if (!auth) {
+        process.exitCode = 1;
+        return;
+      }
     }
     return fn(...args);
   };

package/lib/commands/init.js

@@ -4,7 +4,7 @@
  * Usage: ppcos init <client-name> [--skip-config]
  */
 
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, rmSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -13,7 +13,6 @@ import { calculateChecksum } from '../utils/checksum.js';
 import { createManifest, writeManifest, manifestExists, getManagedType } from '../utils/manifest.js';
 import { getAllFiles, copyFileWithDirs, ensureDir, fileExists } from '../utils/fs-helpers.js';
 import { fetchSkills } from '../utils/skills-fetcher.js';
-import { requireAuth } from '../utils/auth.js';
 import logger from '../utils/logger.js';
 import ora from 'ora';
 
@@ -152,14 +151,17 @@ export default async function init(clientName, options = {}) {
 
   // 3. Fetch skills from API (with local fallback for dev/testing)
   const spinner = ora('Fetching skills from API...').start();
-  let usedLocalFallback = false;
-
   try {
     await fetchSkills(clientDir);
     spinner.succeed('Skills downloaded');
   } catch (error) {
     spinner.fail('Failed to fetch skills');
 
+    // Clean up partial directory from failed download
+    if (existsSync(clientDir)) {
+      rmSync(clientDir, { recursive: true, force: true });
+    }
+
     // Fallback to local .claude-base for development/testing
     const basePath = getBaseTemplatePath();
     if (existsSync(basePath)) {
@@ -171,7 +173,6 @@ export default async function init(clientName, options = {}) {
         const destPath = join(clientDir, relativePath);
         await copyFileWithDirs(srcPath, destPath);
       }
-      usedLocalFallback = true;
     } else {
       logger.error(error.message);
       logger.error('No local fallback available. Run: ppcos login');

package/lib/commands/status.js

@@ -12,7 +12,6 @@ import {
   manifestExists,
   detectModifications
 } from '../utils/manifest.js';
-import { getAllFiles } from '../utils/fs-helpers.js';
 import { readAuth } from '../utils/auth.js';
 import logger from '../utils/logger.js';
 import chalk from 'chalk';
@@ -32,14 +31,6 @@ function getPackageVersion() {
   return pkg.version;
 }
 
-/**
- * Get path to .claude-base template directory
- * @returns {string}
- */
-function getBaseTemplatePath() {
-  return join(PACKAGE_ROOT, '.claude-base');
-}
-
 /**
  * Get clients directory path
  * @returns {string}
@@ -119,18 +110,14 @@ function findCustomSkills(clientDir, manifest) {
 async function getClientStatus(clientName) {
   const clientsDir = getClientsDir();
   const clientDir = join(clientsDir, clientName);
-  const basePath = getBaseTemplatePath();
   const packageVersion = getPackageVersion();
 
   // Read manifest
   const manifest = await readManifest(clientDir);
   const currentVersion = manifest.baseVersion;
 
-  // Get base template files for detecting modifications
-  const baseFiles = await getAllFiles(basePath);
-
-  // Detect modifications
-  const mods = await detectModifications(clientDir, manifest, baseFiles);
+  // Detect modifications (no base files needed — status only uses manifest checksums)
+  const mods = await detectModifications(clientDir, manifest);
 
   // Find custom skills
   const customSkills = findCustomSkills(clientDir, manifest);
@@ -164,15 +151,6 @@ async function getClientStatus(clientName) {
  */
 export default async function status(options = {}) {
   const packageVersion = getPackageVersion();
-  const basePath = getBaseTemplatePath();
-
-  // Check base template exists
-  if (!existsSync(basePath)) {
-    logger.error('Template directory not found. Package may be corrupted.');
-    process.exitCode = 1;
-    return;
-  }
-
   // Discover clients
   let clients = discoverClients();
 
@@ -281,7 +259,6 @@ export default async function status(options = {}) {
 // Export helpers for testing
 export {
   getPackageVersion,
-  getBaseTemplatePath,
   getClientsDir,
   discoverClients,
   findCustomSkills,

package/lib/commands/update.js

@@ -4,7 +4,7 @@
  * Usage: ppcos update [--client <name>] [--dry-run]
  */
 
-import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, readdirSync, unlinkSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
@@ -25,9 +25,9 @@ import {
   createBackupTimestamp
 } from '../utils/fs-helpers.js';
 import { fetchSkills } from '../utils/skills-fetcher.js';
-import { requireAuth } from '../utils/auth.js';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
+import { displayDiffs } from '../utils/diff.js';
 import logger from '../utils/logger.js';
 import ora from 'ora';
 
@@ -75,6 +75,36 @@ async function ensureMemoryFolder(clientDir) {
   }
 }
 
+/**
+ * One-time migration: merge deny rules into settings.local.json
+ * Adds missing deny entries without touching existing config
+ */
+function migrateSettingsDenyRules(clientDir) {
+  const settingsPath = join(clientDir, '.claude', 'settings.local.json');
+  if (!existsSync(settingsPath)) return;
+
+  const requiredDeny = [
+    'Read(./.env)',
+    'Read(./.env.*)',
+    'Read(./secrets/**)'
+  ];
+
+  try {
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    if (!settings.permissions) settings.permissions = {};
+    const existing = settings.permissions.deny || [];
+    const toAdd = requiredDeny.filter(rule => !existing.includes(rule));
+
+    if (toAdd.length === 0) return;
+
+    settings.permissions.deny = [...existing, ...toAdd];
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    logger.info(`  Added ${toAdd.length} deny rule${toAdd.length !== 1 ? 's' : ''} to settings.local.json`);
+  } catch {
+    // Don't fail update over migration
+  }
+}
+
 /**
  * Find all client directories with .managed.json
  * @returns {string[]} Array of client names
@@ -104,21 +134,29 @@ function discoverClients() {
 /**
  * Prompt user for conflict resolution
  * @param {string[]} modifiedFiles - List of modified file paths
- * @returns {Promise<'backup'|'skip'|'cancel'>}
+ * @param {string} clientDir - Path to client directory
+ * @param {string} basePath - Path to base template directory
+ * @returns {Promise<'backup'|'overwrite'|'skip'|'cancel'>}
  */
-async function promptConflictResolution(modifiedFiles) {
+async function promptConflictResolution(modifiedFiles, clientDir, basePath) {
   console.log('');
   logger.warn('Modified files detected:');
   for (const file of modifiedFiles) {
     console.log(`  - ${file}`);
   }
 
-  console.log('');
-  console.log('Options:');
-  console.log('  [1] Backup and overwrite (files saved to .backup/)');
-  console.log('  [2] Skip modified files (keep your changes)');
-  console.log('  [3] Cancel update');
-  console.log('');
+  const showMenu = () => {
+    console.log('');
+    console.log('Options:');
+    console.log('  [d] View differences');
+    console.log('  [1] Backup and overwrite (files saved to .backup/)');
+    console.log('  [2] Overwrite without backup (discard your changes)');
+    console.log('  [3] Skip modified files (keep your changes)');
+    console.log('  [4] Cancel update');
+    console.log('');
+  };
+
+  showMenu();
 
   const rl = createInterface({
     input: process.stdin,
@@ -127,19 +165,26 @@ async function promptConflictResolution(modifiedFiles) {
 
   return new Promise((resolve) => {
     const ask = () => {
-      rl.question('Choice [1/2/3]: ', (answer) => {
-        const choice = answer.trim();
-        if (choice === '1') {
+      rl.question('Choice [d/1/2/3/4]: ', (answer) => {
+        const choice = answer.trim().toLowerCase();
+        if (choice === 'd') {
+          displayDiffs(modifiedFiles, clientDir, basePath);
+          showMenu();
+          ask();
+        } else if (choice === '1') {
           rl.close();
           resolve('backup');
         } else if (choice === '2') {
           rl.close();
-          resolve('skip');
+          resolve('overwrite');
         } else if (choice === '3') {
+          rl.close();
+          resolve('skip');
+        } else if (choice === '4') {
           rl.close();
           resolve('cancel');
         } else {
-          console.log('Invalid choice. Please enter 1, 2, or 3.');
+          console.log('Invalid choice. Please enter d, 1, 2, 3, or 4.');
           ask();
         }
       });
@@ -204,8 +249,9 @@ async function updateClient(clientName, basePathOrOptions = {}, options = {}) {
   const manifest = await readManifest(clientDir);
   const currentVersion = manifest.baseVersion;
 
-  // Auto-create memory folder for existing clients (migration)
+  // Migrations for existing clients
   await ensureMemoryFolder(clientDir);
+  migrateSettingsDenyRules(clientDir);
 
   // Check if already up to date
   if (currentVersion === packageVersion) {
@@ -218,6 +264,28 @@ async function updateClient(clientName, basePathOrOptions = {}, options = {}) {
   // Detect modifications
   const mods = await detectModifications(clientDir, manifest, baseFiles);
 
+  // Guard: if downloaded base is empty or incomplete, something went wrong — abort
+  const managedUpdateFiles = Object.keys(manifest.managedFiles).filter(f => {
+    const managedType = manifest.managedFiles[f].managedType || 'update';
+    return managedType !== 'config';
+  });
+
+  if (managedUpdateFiles.length > 0 && baseFiles.length < managedUpdateFiles.length * 0.5) {
+    logger.error(`  Downloaded template looks incomplete (${baseFiles.length} files vs ${managedUpdateFiles.length} expected) — aborting update for ${clientName}`);
+    return { status: 'cancelled' };
+  }
+
+  // Detect files removed from base template (orphans)
+  const baseFileSet = new Set(baseFiles);
+  const orphanedFiles = Object.keys(manifest.managedFiles).filter(f => {
+    const managedType = manifest.managedFiles[f].managedType || 'update';
+    return managedType !== 'config' && !baseFileSet.has(f);
+  });
+
+  // Separate modified files that are orphaned (handled differently)
+  const orphanSet = new Set(orphanedFiles);
+  const modifiedNonOrphans = mods.modified.filter(f => !orphanSet.has(f));
+
   // Dry run output
   if (options.dryRun) {
     return {
@@ -228,27 +296,28 @@ async function updateClient(clientName, basePathOrOptions = {}, options = {}) {
         unchanged: mods.unchanged.length,
         modified: mods.modified,
         missing: mods.missing,
-        newInBase: mods.newInBase
+        newInBase: mods.newInBase,
+        removedFromBase: orphanedFiles
       }
     };
   }
 
-  // Handle modified files
+  // Handle modified files (excluding orphans, which are handled separately)
   let resolution = null;
   let backedUpFiles = [];
 
-  if (mods.modified.length > 0) {
+  if (modifiedNonOrphans.length > 0) {
     console.log(`Updating ${clientName} (v${currentVersion} → v${packageVersion})`);
-    resolution = await promptConflictResolution(mods.modified);
+    resolution = await promptConflictResolution(modifiedNonOrphans, clientDir, basePath);
 
     if (resolution === 'cancel') {
       return { status: 'cancelled' };
     }
 
     if (resolution === 'backup') {
-      const backupDir = await backupFiles(clientDir, mods.modified);
-      backedUpFiles = mods.modified;
-      console.log(`  Backed up ${mods.modified.length} modified files to ${backupDir.replace(clientDir + '/', '')}`);
+      const backupDir = await backupFiles(clientDir, modifiedNonOrphans);
+      backedUpFiles = modifiedNonOrphans;
+      console.log(`  Backed up ${modifiedNonOrphans.length} modified files to ${backupDir.replace(clientDir + '/', '')}`);
     }
   }
 
@@ -262,7 +331,7 @@ async function updateClient(clientName, basePathOrOptions = {}, options = {}) {
       continue;
     }
 
-    if (mods.modified.includes(file) && resolution === 'skip') {
+    if (modifiedNonOrphans.includes(file) && resolution === 'skip') {
       filesToSkip.push(file);
     } else {
       filesToUpdate.push(file);
@@ -291,16 +360,37 @@ async function updateClient(clientName, basePathOrOptions = {}, options = {}) {
     };
   }
 
+  // Remove orphaned files (removed from base template)
+  let removedCount = 0;
+  if (orphanedFiles.length > 0) {
+    // Back up modified orphans before removing
+    const modifiedOrphans = orphanedFiles.filter(f => mods.modified.includes(f));
+    if (modifiedOrphans.length > 0) {
+      const backupDir = await backupFiles(clientDir, modifiedOrphans);
+      console.log(`  Backed up ${modifiedOrphans.length} modified removed file${modifiedOrphans.length !== 1 ? 's' : ''} to ${backupDir.replace(clientDir + '/', '')}`);
+    }
+
+    for (const relativePath of orphanedFiles) {
+      const fullPath = join(clientDir, relativePath);
+      if (existsSync(fullPath)) {
+        unlinkSync(fullPath);
+        removedCount++;
+      }
+      delete manifest.managedFiles[relativePath];
+    }
+  }
+
   // Update manifest
   manifest.baseVersion = packageVersion;
   manifest.lastUpdated = new Date().toISOString();
+  manifest.conflicts = []; // Clear stale conflicts from previous updates
 
   // Update file entries
   for (const [path, info] of Object.entries(updatedFiles)) {
     manifest.managedFiles[path] = info;
   }
 
-  // Record skipped files as conflicts
+  // Record skipped files as conflicts (only from this update)
   for (const file of filesToSkip) {
     addConflict(manifest, file, 'User modified - skipped during update', packageVersion);
   }
@@ -314,7 +404,8 @@ async function updateClient(clientName, basePathOrOptions = {}, options = {}) {
       toVersion: packageVersion,
       updatedCount: filesToUpdate.length,
       skippedCount: filesToSkip.length,
-      backedUpCount: backedUpFiles.length
+      backedUpCount: backedUpFiles.length,
+      removedCount
     }
   };
 }
@@ -333,19 +424,31 @@ export default async function update(options = {}) {
   const tempDir = mkdtempSync(join(tmpdir(), 'ppcos-update-'));
 
   let basePath;
-  try {
-    await fetchSkills(tempDir);
-    basePath = tempDir;
-    spinner.succeed('Skills downloaded');
-  } catch (error) {
-    spinner.fail('Failed to download skills');
-    logger.error(error.message);
-    logger.info('Falling back to local template if available...');
-
-    // Fallback to local template during migration period
+  if (process.env.PPCOS_DEV) {
+    // Dev mode: use local .claude-base instead of API
     basePath = getBaseTemplatePath();
     if (!existsSync(basePath)) {
-      logger.error('No local template available. Cannot update.');
+      spinner.fail('No local .claude-base found');
+      rmSync(tempDir, { recursive: true, force: true });
+      return;
+    }
+    spinner.succeed('Using local .claude-base (dev mode)');
+    rmSync(tempDir, { recursive: true, force: true });
+  } else {
+    try {
+      await fetchSkills(tempDir);
+      basePath = tempDir;
+      spinner.succeed('Skills downloaded');
+    } catch (error) {
+      spinner.fail('Failed to download skills');
+      logger.error(error.message);
+
+      if (error.message.includes('Not authenticated') || error.message.includes('401') || error.message.includes('expired')) {
+        logger.info('Try: ppcos login');
+      } else {
+        logger.info('Check your internet connection and try again.');
+      }
+
       process.exitCode = 1;
       rmSync(tempDir, { recursive: true, force: true });
       return;
@@ -363,6 +466,7 @@ export default async function update(options = {}) {
     console.log('');
     console.log('Or create main-config.json and run:');
     console.log('  ppcos init-all');
+    rmSync(tempDir, { recursive: true, force: true });
     return;
   }
 
@@ -371,6 +475,7 @@ export default async function update(options = {}) {
     if (!clients.includes(options.client)) {
       logger.error(`Client "${options.client}" not found.`);
       process.exitCode = 1;
+      rmSync(tempDir, { recursive: true, force: true });
       return;
     }
     clients = [options.client];
@@ -416,6 +521,13 @@ export default async function update(options = {}) {
           }
         }
 
+        if (d.removedFromBase.length > 0) {
+          console.log(`  Removed: ${d.removedFromBase.length} files`);
+          for (const file of d.removedFromBase) {
+            console.log(`    - ${file}`);
+          }
+        }
+
         console.log('');
         results.skipped++;
       } else if (result.status === 'up-to-date') {
@@ -432,6 +544,9 @@ export default async function update(options = {}) {
       } else if (result.status === 'updated') {
         const d = result.details;
         console.log(`  Updated ${d.updatedCount} files`);
+        if (d.removedCount > 0) {
+          console.log(`  Removed ${d.removedCount} orphaned files`);
+        }
         if (d.skippedCount > 0) {
           console.log(`  Skipped ${d.skippedCount} modified files`);
         }

package/lib/utils/api-client.js

@@ -111,7 +111,7 @@ export async function downloadSkills(sessionToken) {
       throw new Error(error.error || 'Failed to download skills');
     }
 
-    return response.body;
+    return response;
   } catch (error) {
     logger.error(`API error: ${error.message}`);
     throw error;

package/lib/utils/diff.js

@@ -0,0 +1,74 @@
+/**
+ * Diff utilities - Show file differences in terminal
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createTwoFilesPatch } from 'diff';
+import chalk from 'chalk';
+
+const MAX_DIFF_LINES = 200;
+
+/**
+ * Generate a colored inline diff between two files
+ * @param {string} oldPath - Path to current (user-modified) file
+ * @param {string} newPath - Path to incoming (base template) file
+ * @param {string} label - Display name for the file
+ * @param {number} [maxLines] - Max diff lines to show
+ * @returns {string} Formatted diff string for terminal
+ */
+export function formatFileDiff(oldPath, newPath, label, maxLines = MAX_DIFF_LINES) {
+  const oldContent = readFileSync(oldPath, 'utf8');
+  const newContent = readFileSync(newPath, 'utf8');
+
+  const patch = createTwoFilesPatch(
+    `your version: ${label}`,
+    `incoming update: ${label}`,
+    oldContent,
+    newContent,
+    '', '',
+    { context: 3 }
+  );
+
+  const lines = patch.split('\n');
+  const coloredLines = lines.map(line => {
+    if (line.startsWith('+') && !line.startsWith('+++')) {
+      return chalk.green(line);
+    } else if (line.startsWith('-') && !line.startsWith('---')) {
+      return chalk.red(line);
+    } else if (line.startsWith('@@')) {
+      return chalk.cyan(line);
+    }
+    return line;
+  });
+
+  if (coloredLines.length > maxLines) {
+    const truncated = coloredLines.slice(0, maxLines);
+    truncated.push('');
+    truncated.push(chalk.gray(`  ... ${coloredLines.length - maxLines} more lines (truncated)`));
+    return truncated.join('\n');
+  }
+
+  return coloredLines.join('\n');
+}
+
+/**
+ * Display diffs for all modified files
+ * @param {string[]} modifiedFiles - Relative paths of modified files
+ * @param {string} clientDir - Path to client directory
+ * @param {string} basePath - Path to base template directory
+ */
+export function displayDiffs(modifiedFiles, clientDir, basePath) {
+  console.log('');
+  console.log(chalk.gray(`  ${chalk.red('- red')}   = your version (will be replaced)`));
+  console.log(chalk.gray(`  ${chalk.green('+ green')} = incoming update`));
+
+  for (const file of modifiedFiles) {
+    const clientFile = join(clientDir, file);
+    const baseFile = join(basePath, file);
+
+    console.log('');
+    console.log(chalk.bold.underline(file));
+    console.log(formatFileDiff(clientFile, baseFile, file));
+  }
+  console.log('');
+}

package/lib/utils/skills-fetcher.js

@@ -1,6 +1,7 @@
-import { existsSync, mkdirSync } from 'fs';
-import { Extract } from 'unzipper';
-import { Readable } from 'stream';
+import { existsSync, mkdirSync, writeFileSync, unlinkSync } from 'fs';
+import { Open } from 'unzipper';
+import { join } from 'path';
+import { tmpdir } from 'os';
 import { downloadSkills } from './api-client.js';
 import { readAuth } from './auth.js';
 import logger from './logger.js';
@@ -22,21 +23,22 @@ export async function fetchSkills(targetDir) {
   }
 
   // Download skills
-  const stream = await downloadSkills(auth.sessionToken);
-
-  // Convert web stream to Node stream
-  const nodeStream = Readable.fromWeb(stream);
-
-  // Extract zip — use .pipe() with close event instead of pipeline.
-  // unzipper's Extract doesn't properly signal completion through pipeline,
-  // causing rmSync to delete the temp dir while files are still being written.
-  await new Promise((resolve, reject) => {
-    nodeStream
-      .pipe(Extract({ path: targetDir }))
-      .on('close', resolve)
-      .on('error', reject);
-    nodeStream.on('error', reject);
-  });
+  const response = await downloadSkills(auth.sessionToken);
+
+  // Write zip to temp file first, then extract from disk.
+  // Streaming extraction (Extract) silently drops files when HTTP chunks
+  // don't align with zip entry boundaries. Open.file() reads the central
+  // directory and extracts every entry reliably.
+  const tempZip = join(tmpdir(), `ppcos-skills-${Date.now()}.zip`);
+  try {
+    const buffer = Buffer.from(await response.arrayBuffer());
+    writeFileSync(tempZip, buffer);
+
+    const directory = await Open.file(tempZip);
+await directory.extract({ path: targetDir });
+  } finally {
+    try { unlinkSync(tempZip); } catch {}
+  }
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ppcos",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "CLI tool to manage Google Ads AI workflow skills and agents for Claude Code",
   "type": "module",
   "bin": {
@@ -18,8 +18,9 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
-    "commander": "^12.0.0",
     "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "diff": "^8.0.3",
     "ora": "^8.0.0",
     "unzipper": "^0.12.3"
   },