ppcos 1.0.5 → 1.0.7

package/lib/commands/update.js

@@ -4,352 +4,36 @@
  * Usage: ppcos update [--client <name>] [--dry-run]
  */
 
-import { readFileSync, writeFileSync, existsSync, readdirSync, unlinkSync } from 'node:fs';
-import { join, dirname, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { createInterface } from 'node:readline';
+import { existsSync, unlinkSync } from 'node:fs';
+import { join, sep } from 'node:path';
 import {
   readManifest,
   writeManifest,
   detectModifications,
   addConflict,
-  manifestExists,
   getManagedType,
   isConfigFile
 } from '../utils/manifest.js';
 import { calculateChecksum } from '../utils/checksum.js';
-import {
-  getAllFiles,
-  copyFileWithDirs,
-  ensureDir,
-  createBackupTimestamp
-} from '../utils/fs-helpers.js';
+import { getAllFiles, copyFileWithDirs } from '../utils/fs-helpers.js';
 import { fetchSkills } from '../utils/skills-fetcher.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';
+import {
+  getPackageVersion,
+  getBaseTemplatePath,
+  getClientsDir,
+  discoverClients
+} from '../utils/paths.js';
+import { runAllMigrations } from '../utils/migrations.js';
+import { promptConflictResolution, backupFiles } from '../utils/conflicts.js';
+import updateHub from './update-hub.js';
 
-// Get package root directory
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const PACKAGE_ROOT = join(__dirname, '..', '..');
-
-/**
- * Get package version from package.json
- * @returns {string}
- */
-function getPackageVersion() {
-  const pkgPath = join(PACKAGE_ROOT, 'package.json');
-  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
-  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}
- */
-function getClientsDir() {
-  return join(process.cwd(), 'clients');
-}
-
-/**
- * Ensure memory folder exists in client workspace
- * Creates context/memory/ if it doesn't exist (for existing clients)
- * @param {string} clientDir - Path to client directory
- */
-async function ensureMemoryFolder(clientDir) {
-  const memoryDir = join(clientDir, 'context', 'memory');
-  if (!existsSync(memoryDir)) {
-    await ensureDir(memoryDir);
-    logger.info('  Created context/memory/ folder');
-  }
-}
-
-/**
- * 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
-  }
-}
-
-/**
- * One-time migration: merge hooks config into settings.local.json
- * Adds missing hook events without touching existing ones
- */
-function migrateSettingsHooks(clientDir) {
-  const settingsPath = join(clientDir, '.claude', 'settings.local.json');
-  if (!existsSync(settingsPath)) return;
-
-  const requiredHooks = {
-    SessionStart: [
-      {
-        matcher: 'startup|resume|clear',
-        hooks: [
-          {
-            type: 'command',
-            command: '.claude/hooks/session-context-check.sh',
-            timeout: 30,
-            statusMessage: 'Checking context freshness...'
-          }
-        ]
-      }
-    ],
-    Stop: [
-      {
-        hooks: [
-          {
-            type: 'command',
-            command: '.claude/hooks/stop-memory-check.sh',
-            timeout: 10,
-            statusMessage: 'Checking memory log...'
-          }
-        ]
-      }
-    ],
-    PostCompact: [
-      {
-        hooks: [
-          {
-            type: 'command',
-            command: '.claude/hooks/post-compact-reminder.sh',
-            timeout: 30,
-            statusMessage: 'Restoring context after compaction...'
-          }
-        ]
-      }
-    ]
-  };
-
-  try {
-    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
-    if (!settings.hooks) settings.hooks = {};
-
-    const added = [];
-    for (const [event, config] of Object.entries(requiredHooks)) {
-      if (!settings.hooks[event]) {
-        settings.hooks[event] = config;
-        added.push(event);
-      }
-    }
-
-    if (added.length === 0) return;
-
-    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
-    logger.info(`  Added ${added.length} hook${added.length !== 1 ? 's' : ''} to settings.local.json (${added.join(', ')})`);
-  } catch {
-    // Don't fail update over migration
-  }
-}
-
-/**
- * One-time migration: normalize backslash manifest keys to forward slashes.
- * On Windows, getAllFiles() returned backslash paths which were stored as manifest keys.
- * This normalizes them so lookups work cross-platform.
- */
-function migrateManifestKeys(manifest) {
-  let fixed = 0;
-  for (const [key, value] of Object.entries(manifest.managedFiles)) {
-    const normalized = key.replace(/\\/g, '/');
-    if (normalized !== key) {
-      delete manifest.managedFiles[key];
-      manifest.managedFiles[normalized] = value;
-      fixed++;
-    }
-  }
-  for (const conflict of (manifest.conflicts || [])) {
-    if (conflict.file) {
-      conflict.file = conflict.file.replace(/\\/g, '/');
-    }
-  }
-  if (fixed > 0) {
-    logger.info(`  Normalized ${fixed} manifest key${fixed !== 1 ? 's' : ''}`);
-  }
-}
-
-/**
- * One-time migration: fix managedType for config files.
- * On Windows, isConfigFile() failed due to backslash paths, so config files
- * got stored with managedType 'update' instead of 'config'.
- * This corrects existing manifests in-place (before detectModifications runs).
- */
-function migrateConfigManagedTypes(manifest) {
-  let fixed = 0;
-  for (const [path, info] of Object.entries(manifest.managedFiles)) {
-    if (isConfigFile(path) && info.managedType !== 'config') {
-      info.managedType = 'config';
-      fixed++;
-    }
-  }
-  if (fixed > 0) {
-    logger.info(`  Fixed managedType for ${fixed} config file${fixed !== 1 ? 's' : ''}`);
-  }
-}
-
-/**
- * Find all client directories with .managed.json
- * @returns {string[]} Array of client names
- */
-function discoverClients() {
-  const clientsDir = getClientsDir();
-
-  if (!existsSync(clientsDir)) {
-    return [];
-  }
-
-  const entries = readdirSync(clientsDir, { withFileTypes: true });
-  const clients = [];
-
-  for (const entry of entries) {
-    if (entry.isDirectory()) {
-      const clientDir = join(clientsDir, entry.name);
-      if (manifestExists(clientDir)) {
-        clients.push(entry.name);
-      }
-    }
-  }
-
-  return clients;
-}
-
-/**
- * Prompt user for conflict resolution
- * @param {string[]} modifiedFiles - List of modified file paths
- * @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, clientDir, basePath) {
-  console.log('');
-  logger.warn('Modified files detected:');
-  for (const file of modifiedFiles) {
-    console.log(`  - ${file}`);
-  }
-
-  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,
-    output: process.stdout
-  });
-
-  return new Promise((resolve) => {
-    const ask = () => {
-      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('overwrite');
-        } else if (choice === '3') {
-          rl.close();
-          resolve('skip');
-        } else if (choice === '4') {
-          rl.close();
-          resolve('cancel');
-        } else {
-          console.log('Invalid choice. Please enter d, 1, 2, 3, or 4.');
-          ask();
-        }
-      });
-    };
-    ask();
-  });
-}
-
-/**
- * Backup modified files to .backup/<timestamp>/
- * @param {string} clientDir - Path to client directory
- * @param {string[]} files - Relative paths of files to backup
- * @returns {Promise<string>} Backup folder path
- */
-async function backupFiles(clientDir, files) {
-  const timestamp = createBackupTimestamp();
-  const backupDir = join(clientDir, '.backup', timestamp);
-
-  for (const relativePath of files) {
-    const srcPath = join(clientDir, relativePath);
-    const destPath = join(backupDir, relativePath);
-    await copyFileWithDirs(srcPath, destPath);
-  }
-
-  // Write backup manifest
-  const manifestContent = [
-    `# Backup created during update`,
-    `# ${new Date().toISOString()}`,
-    '',
-    ...files
-  ].join('\n');
-  await ensureDir(backupDir);
-  const { writeFile } = await import('node:fs/promises');
-  await writeFile(join(backupDir, 'manifest.txt'), manifestContent);
-
-  // Verify all files were actually backed up before returning
-  const { readFileSync } = await import('node:fs');
-  for (const relativePath of files) {
-    const backedUpPath = join(backupDir, relativePath);
-    if (!existsSync(backedUpPath)) {
-      throw new Error(`Backup verification failed: ${relativePath} was not created in ${backupDir}`);
-    }
-    // Verify content matches source (guards against empty/placeholder files from cloud sync)
-    const srcContent = readFileSync(join(clientDir, relativePath));
-    const backupContent = readFileSync(backedUpPath);
-    if (!srcContent.equals(backupContent)) {
-      throw new Error(`Backup verification failed: ${relativePath} content mismatch (possible cloud sync interference)`);
-    }
-  }
-
-  return backupDir;
-}
+// Directories to exclude when enumerating client template files.
+// hub-base/ contains hub-level skills that are handled separately.
+const CLIENT_TEMPLATE_EXCLUDE_DIRS = new Set(['tmp', 'hub-base']);
 
 /**
  * Update a single client
@@ -378,19 +62,15 @@ async function updateClient(clientName, basePathOrOptions = {}, options = {}) {
   const currentVersion = manifest.baseVersion;
 
   // Migrations for existing clients
-  await ensureMemoryFolder(clientDir);
-  migrateSettingsDenyRules(clientDir);
-  migrateSettingsHooks(clientDir);
-  migrateManifestKeys(manifest);
-  migrateConfigManagedTypes(manifest);
+  await runAllMigrations(clientDir, manifest);
 
   // Check if already up to date
   if (currentVersion === packageVersion) {
     return { status: 'up-to-date' };
   }
 
-  // Get base template files
-  const baseFiles = await getAllFiles(basePath);
+  // Get base template files (exclude hub-base/ which is handled separately)
+  const baseFiles = await getAllFiles(basePath, basePath, CLIENT_TEMPLATE_EXCLUDE_DIRS);
 
   // Detect modifications
   const mods = await detectModifications(clientDir, manifest, baseFiles);
@@ -612,6 +292,9 @@ export default async function update(options = {}) {
     }
   }
 
+  // Update hub-level skills (before client updates)
+  await updateHub(basePath, options);
+
   // Discover clients
   let clients = discoverClients();
 
@@ -742,11 +425,7 @@ export default async function update(options = {}) {
 }
 
 // Export helpers for testing
-export {
-  getPackageVersion,
-  getBaseTemplatePath,
-  getClientsDir,
-  discoverClients,
-  backupFiles,
-  updateClient
-};
+export { updateClient };
+export { default as updateHub } from './update-hub.js';
+export { backupFiles } from '../utils/conflicts.js';
+export { getPackageVersion, getBaseTemplatePath, getHubBasePath, getClientsDir, discoverClients } from '../utils/paths.js';

package/lib/utils/conflicts.js

@@ -0,0 +1,119 @@
+/**
+ * Conflict resolution and file backup utilities.
+ *
+ * Used by update commands when managed files have been
+ * modified by the user since the last update.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { copyFileWithDirs, ensureDir, createBackupTimestamp } from './fs-helpers.js';
+import { displayDiffs } from './diff.js';
+import logger from './logger.js';
+
+/**
+ * Prompt user for conflict resolution
+ * @param {string[]} modifiedFiles - List of modified file paths
+ * @param {string} clientDir - Path to client directory
+ * @param {string} basePath - Path to base template directory
+ * @returns {Promise<'backup'|'overwrite'|'skip'|'cancel'>}
+ */
+export async function promptConflictResolution(modifiedFiles, clientDir, basePath) {
+  console.log('');
+  logger.warn('Modified files detected:');
+  for (const file of modifiedFiles) {
+    console.log(`  - ${file}`);
+  }
+
+  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,
+    output: process.stdout
+  });
+
+  return new Promise((resolve) => {
+    const ask = () => {
+      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('overwrite');
+        } else if (choice === '3') {
+          rl.close();
+          resolve('skip');
+        } else if (choice === '4') {
+          rl.close();
+          resolve('cancel');
+        } else {
+          console.log('Invalid choice. Please enter d, 1, 2, 3, or 4.');
+          ask();
+        }
+      });
+    };
+    ask();
+  });
+}
+
+/**
+ * Backup modified files to .backup/<timestamp>/
+ * @param {string} clientDir - Path to client directory
+ * @param {string[]} files - Relative paths of files to backup
+ * @returns {Promise<string>} Backup folder path
+ */
+export async function backupFiles(clientDir, files) {
+  const timestamp = createBackupTimestamp();
+  const backupDir = join(clientDir, '.backup', timestamp);
+
+  for (const relativePath of files) {
+    const srcPath = join(clientDir, relativePath);
+    const destPath = join(backupDir, relativePath);
+    await copyFileWithDirs(srcPath, destPath);
+  }
+
+  // Write backup manifest
+  const manifestContent = [
+    `# Backup created during update`,
+    `# ${new Date().toISOString()}`,
+    '',
+    ...files
+  ].join('\n');
+  await ensureDir(backupDir);
+  await writeFile(join(backupDir, 'manifest.txt'), manifestContent);
+
+  // Verify all files were actually backed up before returning
+  for (const relativePath of files) {
+    const backedUpPath = join(backupDir, relativePath);
+    if (!existsSync(backedUpPath)) {
+      throw new Error(`Backup verification failed: ${relativePath} was not created in ${backupDir}`);
+    }
+    // Verify content matches source (guards against empty/placeholder files from cloud sync)
+    const srcContent = readFileSync(join(clientDir, relativePath));
+    const backupContent = readFileSync(backedUpPath);
+    if (!srcContent.equals(backupContent)) {
+      throw new Error(`Backup verification failed: ${relativePath} content mismatch (possible cloud sync interference)`);
+    }
+  }
+
+  return backupDir;
+}

package/lib/utils/fs-helpers.js

@@ -7,6 +7,11 @@ import { readdirSync, statSync, mkdirSync, copyFileSync, existsSync, chmodSync }
 import { join, relative, dirname } from 'node:path';
 import { constants } from 'node:fs';
 
+// Directories to skip during template file enumeration.
+// tmp/ dirs hold generated runtime data (analysis output, caches)
+// that must never be distributed to clients.
+const EXCLUDED_DIR_NAMES = new Set(['tmp']);
+
 /**
  * Check if a file exists (async)
  * @param {string} filePath - Path to check
@@ -36,14 +41,15 @@ export function fileExistsSync(filePath) {
  * @param {string} [baseDir] - Base directory for relative paths
  * @returns {Promise<string[]>} Array of relative file paths
  */
-export async function getAllFiles(dir, baseDir = dir) {
+export async function getAllFiles(dir, baseDir = dir, excludeDirs = EXCLUDED_DIR_NAMES) {
   const files = [];
   const entries = await readdir(dir, { withFileTypes: true });
 
   for (const entry of entries) {
     const fullPath = join(dir, entry.name);
     if (entry.isDirectory()) {
-      files.push(...await getAllFiles(fullPath, baseDir));
+      if (excludeDirs.has(entry.name)) continue;
+      files.push(...await getAllFiles(fullPath, baseDir, excludeDirs));
     } else {
       files.push(relative(baseDir, fullPath).replace(/\\/g, '/'));
     }
@@ -58,14 +64,15 @@ export async function getAllFiles(dir, baseDir = dir) {
  * @param {string} [baseDir] - Base directory for relative paths
  * @returns {string[]} Array of relative file paths
  */
-export function getAllFilesSync(dir, baseDir = dir) {
+export function getAllFilesSync(dir, baseDir = dir, excludeDirs = EXCLUDED_DIR_NAMES) {
   const files = [];
   const entries = readdirSync(dir, { withFileTypes: true });
 
   for (const entry of entries) {
     const fullPath = join(dir, entry.name);
     if (entry.isDirectory()) {
-      files.push(...getAllFilesSync(fullPath, baseDir));
+      if (excludeDirs.has(entry.name)) continue;
+      files.push(...getAllFilesSync(fullPath, baseDir, excludeDirs));
     } else {
       files.push(relative(baseDir, fullPath).replace(/\\/g, '/'));
     }

package/lib/utils/manifest.js

@@ -9,6 +9,7 @@ import { calculateChecksum } from './checksum.js';
 import { fileExists } from './fs-helpers.js';
 
 const MANIFEST_FILENAME = '.managed.json';
+const HUB_MANIFEST_FILENAME = '.managed-hub.json';
 const SCHEMA_VERSION = '1.0';
 
 // Files that should be config-only (init once, never update)
@@ -117,6 +118,44 @@ export function manifestExists(clientDir) {
   return existsSync(join(clientDir, MANIFEST_FILENAME));
 }
 
+// --- Hub manifest functions ---
+
+/**
+ * Read .managed-hub.json from the hub root directory (async)
+ * @param {string} hubDir - Path to hub root directory
+ * @returns {Promise<object>} Parsed manifest
+ */
+export async function readHubManifest(hubDir) {
+  const manifestPath = join(hubDir, HUB_MANIFEST_FILENAME);
+  const content = await readFile(manifestPath, 'utf8');
+  const manifest = JSON.parse(content);
+
+  if (manifest.schemaVersion !== SCHEMA_VERSION) {
+    throw new Error(`Unsupported hub manifest schema version: ${manifest.schemaVersion}`);
+  }
+
+  return manifest;
+}
+
+/**
+ * Write .managed-hub.json to the hub root directory (async)
+ * @param {string} hubDir - Path to hub root directory
+ * @param {object} manifest - Manifest object to write
+ */
+export async function writeHubManifest(hubDir, manifest) {
+  const manifestPath = join(hubDir, HUB_MANIFEST_FILENAME);
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+}
+
+/**
+ * Check if a hub manifest exists
+ * @param {string} hubDir - Path to hub root directory
+ * @returns {boolean}
+ */
+export function hubManifestExists(hubDir) {
+  return existsSync(join(hubDir, HUB_MANIFEST_FILENAME));
+}
+
 /**
  * Detect modifications to managed files
  * @param {string} clientDir - Path to client directory