ppcos 0.3.0

package/lib/utils/auth.js

@@ -0,0 +1,117 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import logger from './logger.js';
+
+/**
+ * Get path to PPCOS config file
+ */
+export function getConfigPath() {
+  return join(homedir(), '.ppcos', 'config.json');
+}
+
+/**
+ * Ensure config directory exists
+ */
+function ensureConfigDir() {
+  const configPath = getConfigPath();
+  const dir = dirname(configPath);
+
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Read entire config file
+ */
+export function readConfig() {
+  try {
+    const configPath = getConfigPath();
+    if (!existsSync(configPath)) {
+      return {};
+    }
+    return JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch (error) {
+    logger.error(`Failed to read config: ${error.message}`);
+    return {};
+  }
+}
+
+/**
+ * Write entire config file
+ */
+export function writeConfig(config) {
+  try {
+    ensureConfigDir();
+    const configPath = getConfigPath();
+    writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
+  } catch (error) {
+    logger.error(`Failed to write config: ${error.message}`);
+  }
+}
+
+/**
+ * Read auth data from config
+ */
+export function readAuth() {
+  const config = readConfig();
+  return config.auth || null;
+}
+
+/**
+ * Write auth data to config
+ */
+export function writeAuth(authData) {
+  const config = readConfig();
+  config.auth = authData;
+  writeConfig(config);
+}
+
+/**
+ * Clear auth data from config
+ */
+export function clearAuth() {
+  const config = readConfig();
+  delete config.auth;
+  writeConfig(config);
+}
+
+/**
+ * Check if user is authenticated with valid session
+ * Returns auth data if valid, false otherwise
+ */
+export function requireAuth() {
+  const auth = readAuth();
+
+  if (!auth?.sessionToken) {
+    logger.error('Authentication required. Run: ppcos login');
+    return false;
+  }
+
+  if (!auth.expiresAt) {
+    logger.error('Invalid session. Run: ppcos login');
+    return false;
+  }
+
+  const expiresAt = new Date(auth.expiresAt);
+  if (expiresAt < new Date()) {
+    logger.error('Session expired. Run: ppcos login');
+    return false;
+  }
+
+  return auth;
+}
+
+/**
+ * Check if session is about to expire (less than 2 hours left)
+ */
+export function isSessionExpiring() {
+  const auth = readAuth();
+  if (!auth?.expiresAt) return false;
+
+  const expiresAt = new Date(auth.expiresAt);
+  const twoHoursFromNow = new Date(Date.now() + 2 * 60 * 60 * 1000);
+
+  return expiresAt < twoHoursFromNow;
+}

package/lib/utils/checksum.js

@@ -0,0 +1,61 @@
+/**
+ * Checksum utilities - SHA256 calculations for files
+ */
+
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+
+/**
+ * Calculate SHA256 checksum of a file (async)
+ * @param {string} filePath - Path to file
+ * @returns {Promise<string>} Checksum with "sha256:" prefix
+ */
+export async function calculateChecksum(filePath) {
+  const content = await readFile(filePath);
+  const hash = createHash('sha256').update(content).digest('hex');
+  return `sha256:${hash}`;
+}
+
+/**
+ * Calculate SHA256 checksum of a file (sync)
+ * @param {string} filePath - Path to file
+ * @returns {string} Checksum with "sha256:" prefix
+ */
+export function calculateChecksumSync(filePath) {
+  const content = readFileSync(filePath);
+  const hash = createHash('sha256').update(content).digest('hex');
+  return `sha256:${hash}`;
+}
+
+/**
+ * Calculate SHA256 checksum from content
+ * @param {string|Buffer} content - Content to hash
+ * @returns {string} Checksum with "sha256:" prefix
+ */
+export function checksumFromContent(content) {
+  const hash = createHash('sha256').update(content).digest('hex');
+  return `sha256:${hash}`;
+}
+
+/**
+ * Verify a file's checksum matches expected value
+ * @param {string} filePath - Path to file
+ * @param {string} expectedChecksum - Expected checksum (with sha256: prefix)
+ * @returns {Promise<boolean>} True if checksums match
+ */
+export async function verifyChecksum(filePath, expectedChecksum) {
+  const actualChecksum = await calculateChecksum(filePath);
+  return actualChecksum === expectedChecksum;
+}
+
+/**
+ * Verify a file's checksum matches expected value (sync)
+ * @param {string} filePath - Path to file
+ * @param {string} expectedChecksum - Expected checksum (with sha256: prefix)
+ * @returns {boolean} True if checksums match
+ */
+export function verifyChecksumSync(filePath, expectedChecksum) {
+  const actualChecksum = calculateChecksumSync(filePath);
+  return actualChecksum === expectedChecksum;
+}

package/lib/utils/fs-helpers.js

@@ -0,0 +1,172 @@
+/**
+ * File system helper utilities
+ */
+
+import { readdir, stat, mkdir, copyFile, access } from 'node:fs/promises';
+import { readdirSync, statSync, mkdirSync, copyFileSync, existsSync } from 'node:fs';
+import { join, relative, dirname } from 'node:path';
+import { constants } from 'node:fs';
+
+/**
+ * Check if a file exists (async)
+ * @param {string} filePath - Path to check
+ * @returns {Promise<boolean>}
+ */
+export async function fileExists(filePath) {
+  try {
+    await access(filePath, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a file exists (sync)
+ * @param {string} filePath - Path to check
+ * @returns {boolean}
+ */
+export function fileExistsSync(filePath) {
+  return existsSync(filePath);
+}
+
+/**
+ * Recursively get all files in a directory (async)
+ * @param {string} dir - Directory to scan
+ * @param {string} [baseDir] - Base directory for relative paths
+ * @returns {Promise<string[]>} Array of relative file paths
+ */
+export async function getAllFiles(dir, baseDir = dir) {
+  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));
+    } else {
+      files.push(relative(baseDir, fullPath));
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Recursively get all files in a directory (sync)
+ * @param {string} dir - Directory to scan
+ * @param {string} [baseDir] - Base directory for relative paths
+ * @returns {string[]} Array of relative file paths
+ */
+export function getAllFilesSync(dir, baseDir = dir) {
+  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));
+    } else {
+      files.push(relative(baseDir, fullPath));
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Copy a file, creating parent directories as needed (async)
+ * @param {string} src - Source file path
+ * @param {string} dest - Destination file path
+ */
+export async function copyFileWithDirs(src, dest) {
+  const destDir = dirname(dest);
+  await mkdir(destDir, { recursive: true });
+  await copyFile(src, dest);
+}
+
+/**
+ * Copy a file, creating parent directories as needed (sync)
+ * @param {string} src - Source file path
+ * @param {string} dest - Destination file path
+ */
+export function copyFileWithDirsSync(src, dest) {
+  const destDir = dirname(dest);
+  if (!existsSync(destDir)) {
+    mkdirSync(destDir, { recursive: true });
+  }
+  copyFileSync(src, dest);
+}
+
+/**
+ * Ensure a directory exists (async)
+ * @param {string} dir - Directory path
+ */
+export async function ensureDir(dir) {
+  await mkdir(dir, { recursive: true });
+}
+
+/**
+ * Ensure a directory exists (sync)
+ * @param {string} dir - Directory path
+ */
+export function ensureDirSync(dir) {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Check if a path is a directory
+ * @param {string} path - Path to check
+ * @returns {Promise<boolean>}
+ */
+export async function isDirectory(path) {
+  try {
+    const stats = await stat(path);
+    return stats.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a path is a directory (sync)
+ * @param {string} path - Path to check
+ * @returns {boolean}
+ */
+export function isDirectorySync(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Copy all files from source to destination directory
+ * @param {string} srcDir - Source directory
+ * @param {string} destDir - Destination directory
+ * @returns {Promise<string[]>} List of copied relative paths
+ */
+export async function copyDirectory(srcDir, destDir) {
+  const files = await getAllFiles(srcDir);
+  const copied = [];
+
+  for (const relativePath of files) {
+    const src = join(srcDir, relativePath);
+    const dest = join(destDir, relativePath);
+    await copyFileWithDirs(src, dest);
+    copied.push(relativePath);
+  }
+
+  return copied;
+}
+
+/**
+ * Create a timestamped backup directory name
+ * @returns {string} ISO timestamp formatted for filesystem (no colons)
+ */
+export function createBackupTimestamp() {
+  return new Date().toISOString().replace(/:/g, '').replace(/\.\d{3}Z$/, '');
+}

package/lib/utils/logger.js

@@ -0,0 +1,51 @@
+/**
+ * Logger utilities - Colored console output
+ *
+ * Implementation: Phase 4
+ */
+
+import chalk from 'chalk';
+
+/**
+ * Log a success message
+ * @param {string} message
+ */
+export function success(message) {
+  console.log(chalk.green('✓'), message);
+}
+
+/**
+ * Log an error message
+ * @param {string} message
+ */
+export function error(message) {
+  console.log(chalk.red('✗'), message);
+}
+
+/**
+ * Log a warning message
+ * @param {string} message
+ */
+export function warn(message) {
+  console.log(chalk.yellow('⚠'), message);
+}
+
+/**
+ * Log an info message
+ * @param {string} message
+ */
+export function info(message) {
+  console.log(chalk.blue('ℹ'), message);
+}
+
+/**
+ * Log a debug message (only if DEBUG env var is set)
+ * @param {string} message
+ */
+export function debug(message) {
+  if (process.env.DEBUG) {
+    console.log(chalk.gray('[debug]'), message);
+  }
+}
+
+export default { success, error, warn, info, debug };

package/lib/utils/manifest.js

@@ -0,0 +1,212 @@
+/**
+ * Manifest utilities - .managed.json handling
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { calculateChecksum } from './checksum.js';
+import { fileExists } from './fs-helpers.js';
+
+const MANIFEST_FILENAME = '.managed.json';
+const SCHEMA_VERSION = '1.0';
+
+// Files that should be config-only (init once, never update)
+const CONFIG_ONLY_FILES = new Set([
+  'config/ads-context.config.json',
+  '.claude/settings.local.json',
+  'config/.env'
+]);
+
+/**
+ * Check if a file should be treated as config-only
+ * @param {string} relativePath - Relative path from client root
+ * @returns {boolean}
+ */
+export function isConfigFile(relativePath) {
+  return CONFIG_ONLY_FILES.has(relativePath);
+}
+
+/**
+ * Get the managed type for a file
+ * @param {string} relativePath - Relative path from client root
+ * @returns {'update'|'config'}
+ */
+export function getManagedType(relativePath) {
+  return isConfigFile(relativePath) ? 'config' : 'update';
+}
+
+/**
+ * Read .managed.json from a client directory (async)
+ * @param {string} clientDir - Path to client directory
+ * @returns {Promise<object>} Parsed manifest
+ * @throws {Error} If manifest doesn't exist or is invalid
+ */
+export async function readManifest(clientDir) {
+  const manifestPath = join(clientDir, MANIFEST_FILENAME);
+  const content = await readFile(manifestPath, 'utf8');
+  const manifest = JSON.parse(content);
+
+  if (manifest.schemaVersion !== SCHEMA_VERSION) {
+    throw new Error(`Unsupported manifest schema version: ${manifest.schemaVersion}`);
+  }
+
+  return manifest;
+}
+
+/**
+ * Read .managed.json from a client directory (sync)
+ * @param {string} clientDir - Path to client directory
+ * @returns {object|null} Parsed manifest or null if not found
+ */
+export function readManifestSync(clientDir) {
+  const manifestPath = join(clientDir, MANIFEST_FILENAME);
+  if (!existsSync(manifestPath)) {
+    return null;
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  return manifest;
+}
+
+/**
+ * Write .managed.json to a client directory (async)
+ * @param {string} clientDir - Path to client directory
+ * @param {object} manifest - Manifest object to write
+ */
+export async function writeManifest(clientDir, manifest) {
+  const manifestPath = join(clientDir, MANIFEST_FILENAME);
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+}
+
+/**
+ * Write .managed.json to a client directory (sync)
+ * @param {string} clientDir - Path to client directory
+ * @param {object} manifest - Manifest object to write
+ */
+export function writeManifestSync(clientDir, manifest) {
+  const manifestPath = join(clientDir, MANIFEST_FILENAME);
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+}
+
+/**
+ * Create a new manifest object
+ * @param {string} version - Base version (semver)
+ * @param {Object<string, {checksum: string, version: string}>} files - Map of relative paths to file info
+ * @returns {object} New manifest object
+ */
+export function createManifest(version, files) {
+  const now = new Date().toISOString();
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    baseVersion: version,
+    installedAt: now,
+    lastUpdated: now,
+    managedFiles: files,
+    conflicts: []
+  };
+}
+
+/**
+ * Check if a manifest exists for a client
+ * @param {string} clientDir - Path to client directory
+ * @returns {boolean}
+ */
+export function manifestExists(clientDir) {
+  return existsSync(join(clientDir, MANIFEST_FILENAME));
+}
+
+/**
+ * Detect modifications to managed files
+ * @param {string} clientDir - Path to client directory
+ * @param {object} manifest - The manifest object
+ * @param {string[]} [baseFiles] - Files in base template (for detecting new files)
+ * @returns {Promise<{unchanged: string[], modified: string[], missing: string[], newInBase: string[], configSkipped: string[]}>}
+ */
+export async function detectModifications(clientDir, manifest, baseFiles = []) {
+  const results = {
+    unchanged: [],
+    modified: [],
+    missing: [],
+    newInBase: [],
+    configSkipped: []
+  };
+
+  // Check existing managed files
+  for (const [relativePath, info] of Object.entries(manifest.managedFiles)) {
+    const fullPath = join(clientDir, relativePath);
+
+    // Skip config files entirely (never update them)
+    const managedType = info.managedType || 'update';
+    if (managedType === 'config') {
+      results.configSkipped.push(relativePath);
+      continue;
+    }
+
+    if (!await fileExists(fullPath)) {
+      results.missing.push(relativePath);
+      continue;
+    }
+
+    const currentChecksum = await calculateChecksum(fullPath);
+    if (currentChecksum === info.checksum) {
+      results.unchanged.push(relativePath);
+    } else {
+      results.modified.push(relativePath);
+    }
+  }
+
+  // Check for new files in base template
+  for (const relativePath of baseFiles) {
+    // Skip config files when checking for new files
+    if (isConfigFile(relativePath)) {
+      continue;
+    }
+
+    if (!manifest.managedFiles[relativePath]) {
+      results.newInBase.push(relativePath);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Check if a file is a custom (non-managed) file
+ * @param {string} relativePath - Relative path from client root
+ * @param {object} manifest - The manifest object
+ * @returns {boolean}
+ */
+export function isCustomFile(relativePath, manifest) {
+  return !Object.prototype.hasOwnProperty.call(manifest.managedFiles, relativePath);
+}
+
+/**
+ * Add a conflict to the manifest
+ * @param {object} manifest - The manifest object (mutated)
+ * @param {string} file - File path
+ * @param {string} reason - Reason for conflict
+ * @param {string} skippedVersion - Version that was skipped
+ */
+export function addConflict(manifest, file, reason, skippedVersion) {
+  manifest.conflicts.push({
+    file,
+    reason,
+    skippedVersion,
+    skippedAt: new Date().toISOString()
+  });
+}
+
+/**
+ * Update manifest after successful update
+ * @param {object} manifest - The manifest object (mutated)
+ * @param {string} newVersion - New base version
+ * @param {Object<string, {checksum: string, version: string}>} updatedFiles - Updated file info
+ */
+export function updateManifest(manifest, newVersion, updatedFiles) {
+  manifest.baseVersion = newVersion;
+  manifest.lastUpdated = new Date().toISOString();
+
+  for (const [path, info] of Object.entries(updatedFiles)) {
+    manifest.managedFiles[path] = info;
+  }
+}

package/lib/utils/skills-fetcher.js

@@ -0,0 +1,50 @@
+import { createWriteStream, existsSync, mkdirSync } from 'fs';
+import { pipeline } from 'stream/promises';
+import { Extract } from 'unzipper';
+import { Readable } from 'stream';
+import { downloadSkills } from './api-client.js';
+import { readAuth } from './auth.js';
+import logger from './logger.js';
+
+/**
+ * Fetch skills from API and extract to target directory
+ * @param {string} targetDir - Directory to extract skills into
+ */
+export async function fetchSkills(targetDir) {
+  const auth = readAuth();
+
+  if (!auth?.sessionToken) {
+    throw new Error('Not authenticated');
+  }
+
+  // Ensure target directory exists
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true });
+  }
+
+  // Download skills
+  const stream = await downloadSkills(auth.sessionToken);
+
+  // Convert web stream to Node stream
+  const nodeStream = Readable.fromWeb(stream);
+
+  // Extract zip to target directory
+  await pipeline(
+    nodeStream,
+    Extract({ path: targetDir })
+  );
+}
+
+/**
+ * Update existing skills directory with latest from API
+ * @param {string} targetDir - Directory to update
+ */
+export async function updateSkills(targetDir) {
+  if (!existsSync(targetDir)) {
+    throw new Error(`Directory does not exist: ${targetDir}`);
+  }
+
+  // For now, just fetch (which will overwrite)
+  // Later we can add checksum comparison to only update changed files
+  await fetchSkills(targetDir);
+}