ppcos 0.3.0

package/LICENSE

@@ -0,0 +1,9 @@
+Terms of Use
+
+This software is licensed for personal and internal business use only under the PPC Mastery General Terms & Conditions. Use it to become better at your job. Don't use it to build things you sell to others.
+
+Violations may be detected through embedded document fingerprints and will be pursued under Article 13 (Intellectual Property) of the PPC Mastery General Terms.
+
+Full terms: https://www.ppcmastery.com/terms-and-conditions
+
+© 2026 PPC Mastery B.V. All rights reserved.

package/README.md

@@ -0,0 +1,246 @@
+# ppcos-cli
+
+CLI tool to distribute and manage Claude Code skills and agents for Google Ads workflows.
+
+## Installation
+
+```bash
+npm install -g ppcos
+```
+
+Requires Node.js 18+.
+
+## Quick Start
+
+```bash
+# Create a hub folder and navigate to it
+mkdir ppcos-hub && cd ppcos-hub
+
+# Create main-config.json template
+ppcos init
+
+# Edit main-config.json with your client names, then:
+ppcos init-all
+
+# Check status of all clients
+ppcos status
+
+# Update all clients when new version is released
+ppcos update
+```
+
+## Commands
+
+### `ppcos init [client-name]`
+
+Without args: create main-config.json template.
+With client name: create a client workspace.
+
+```bash
+ppcos init                            # Create main-config.json template
+ppcos init client-acme                # Create client workspace
+ppcos init client-acme --skip-config  # Don't add to main-config.json
+```
+
+Creates:
+```
+clients/client-acme/
+├── .managed.json          # Tracks managed files
+├── .claude/
+│   ├── skills/            # 6 Google Ads skills
+│   ├── agents/            # 4 specialized agents
+│   └── settings.local.json
+├── CLAUDE.md              # Client context template
+├── config/                # API credentials
+├── context/               # Client data
+└── created/               # Generated assets
+```
+
+### `ppcos init-all`
+
+Initialize all clients defined in main-config.json.
+
+```bash
+ppcos init-all
+ppcos init-all --force  # Reinitialize existing clients (backs up first)
+```
+
+**main-config.json example:**
+```json
+{
+  "version": "1.0",
+  "clients": [
+    { "name": "client-acme", "enabled": true },
+    { "name": "client-beta", "enabled": true },
+    { "name": "client-gamma", "enabled": false }
+  ]
+}
+```
+
+### `ppcos update`
+
+Update base skills in all clients while preserving custom work.
+
+```bash
+ppcos update                    # Update all clients
+ppcos update --client acme      # Update specific client
+ppcos update --dry-run          # Show what would change
+```
+
+**Conflict handling:**
+- Unchanged files: automatically updated
+- Modified files: prompts with options (backup/skip/cancel)
+- Custom files: never touched
+
+```
+Updating client-acme (v1.0.0 → v1.1.0)
+
+⚠ Modified files detected:
+  - .claude/skills/rsa-maker/SKILL.md
+
+Options:
+  [1] Backup and overwrite (files saved to .backup/)
+  [2] Skip modified files (keep your changes)
+  [3] Cancel update
+
+Choice [1/2/3]:
+```
+
+### `ppcos status`
+
+Show version and modification status for all clients.
+
+```bash
+ppcos status
+ppcos status --client acme  # Show specific client only
+```
+
+Output:
+```
+ppcos-hub/
+
+  client-acme
+    Version: 1.0.0 → 1.1.0 available
+    Managed: 42 files
+    Modified: 2 files
+      - .claude/skills/rsa-maker/SKILL.md
+    Custom: 1 skill
+    Conflicts: 0
+
+  client-beta
+    Version: 1.1.0 (up to date)
+    Managed: 42 files
+    Modified: 0 files
+    Custom: 0 skills
+    Conflicts: 0
+
+Package version: 1.1.0
+```
+
+## Included Skills
+
+| Skill | Description |
+|-------|-------------|
+| `gads-context` | Pull Google Ads account data (campaigns, ads, keywords) |
+| `competitor-scraper` | Fetch competitor ads via DataForSEO API |
+| `ads-context-gatherer` | Gather brand context from websites |
+| `offer-angles` | Extract offer message angles for RSA composition |
+| `rsa-maker` | Create Responsive Search Ads from offer angles |
+| `search-term-analyzer` | Analyze search terms for keyword opportunities |
+| `account-changelog` | Fetch account change history from Google Ads |
+| `landing-page-builder` | Generate high-converting landing page wireframes |
+| `ecom-page-builder` | Generate ecommerce page wireframes with product-first layouts |
+
+## Included Agents
+
+| Agent | Description |
+|-------|-------------|
+| `qs-decider` | Quality Score improvement coordinator |
+| `ad-relevance-analyzer` | Analyze ad relevance issues |
+| `expected-ctr-analyzer` | Analyze expected CTR issues |
+| `landing-page-analyzer` | Analyze landing page experience |
+
+## How It Works
+
+### Managed vs Custom Files
+
+- **Managed files**: Created by `init`, tracked in `.managed.json`, updated by CLI
+- **Custom files**: Created by you, never touched by updates
+
+Add your own skills to `.claude/skills/` - they'll never be modified.
+
+### Update Safety
+
+1. Calculates SHA256 checksum of each managed file
+2. Compares with stored checksum in `.managed.json`
+3. Unchanged files: updated silently
+4. Modified files: user prompted (backup/skip/cancel)
+5. Custom files: completely ignored
+
+### Typical Workflow
+
+```bash
+# Setup (once)
+mkdir ppcos-hub && cd ppcos-hub
+ppcos init client-acme
+cd clients/client-acme
+
+# Daily work
+# Edit CLAUDE.md with client context
+# Run /ppcos to gather brand info
+# Create ads with /rsa-maker
+
+# When CLI updates
+cd ../..
+ppcos update
+```
+
+## Configuration
+
+### config/.env.example
+
+Template for API credentials. Copy to `.env` and fill in:
+
+```
+GOOGLE_ADS_DEVELOPER_TOKEN=your_token
+GOOGLE_ADS_CLIENT_ID=your_client_id
+GOOGLE_ADS_CLIENT_SECRET=your_client_secret
+GOOGLE_ADS_REFRESH_TOKEN=your_refresh_token
+DATAFORSEO_USERNAME=your_username
+DATAFORSEO_PASSWORD=your_password
+```
+
+### config/ads-context.config.json
+
+Per-client settings:
+
+```json
+{
+  "customerId": "1234567890",
+  "competitors": ["competitor1.com", "competitor2.com"],
+  "targetLocations": ["United States"]
+}
+```
+
+## Adding Skills to the Base
+
+To add a new skill that gets distributed to all clients:
+
+1. Create the skill folder in `.claude-base/.claude/skills/<skill-name>/` with at minimum a `SKILL.md`
+2. Bump the package version:
+   ```bash
+   npm version patch  # 1.0.0 → 1.0.1
+   ```
+3. Push to GitHub
+
+Existing clients will receive the new skill on their next `ppcos update`. New clients get it automatically via `ppcos init`.
+
+The same applies to agents (`.claude-base/.claude/agents/`) and any other base template files.
+
+**Why the version bump matters:** The update command compares `package.json` version against each client's stored version. Without a bump, `ppcos update` sees clients as up-to-date and skips them.
+
+## License
+
+Licensed for personal and internal business use only under the [PPC Mastery General Terms & Conditions](https://www.ppcmastery.com/terms-and-conditions).
+
+© 2026 PPC Mastery B.V. All rights reserved.

package/bin/ppcos.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+// Import commands
+import init from '../lib/commands/init.js';
+import initAll from '../lib/commands/init-all.js';
+import update from '../lib/commands/update.js';
+import status from '../lib/commands/status.js';
+import { login } from '../lib/commands/login.js';
+import { logout } from '../lib/commands/logout.js';
+import { whoami } from '../lib/commands/whoami.js';
+import { requireAuth } from '../lib/utils/auth.js';
+
+// Get package.json for version
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+/**
+ * Wrap a command handler with authentication check
+ */
+function gated(fn) {
+  return async (...args) => {
+    const auth = requireAuth();
+    if (!auth) {
+      process.exitCode = 1;
+      return;
+    }
+    return fn(...args);
+  };
+}
+
+const program = new Command();
+
+program
+  .name('ppcos')
+  .description('CLI tool to manage Google Ads AI workflow skills and agents for Claude Code')
+  .version(pkg.version);
+
+// login — NOT gated
+program
+  .command('login')
+  .description('Log in with Circle.so membership (email + OTP)')
+  .action(login);
+
+// logout — NOT gated
+program
+  .command('logout')
+  .description('Log out and clear session')
+  .action(logout);
+
+// whoami — NOT gated
+program
+  .command('whoami')
+  .description('Show current authentication status')
+  .action(whoami);
+
+// init [client-name]
+program
+  .command('init [client-name]')
+  .description('Create main-config.json template, or with <client-name> create a client workspace')
+  .option('--skip-config', 'Don\'t add client to main-config.json')
+  .action(gated(init));
+
+// init-all
+program
+  .command('init-all')
+  .description('Initialize all clients defined in main-config.json')
+  .option('--force', 'Reinitialize existing clients (backs up first)')
+  .action(gated(initAll));
+
+// update
+program
+  .command('update')
+  .description('Update base skills in all clients while preserving custom work')
+  .option('--client <name>', 'Update only this client')
+  .option('--dry-run', 'Show changes without applying')
+  .action(gated(update));
+
+// status
+program
+  .command('status')
+  .description('Show version and modification status for all clients')
+  .option('--client <name>', 'Show only this client')
+  .action(gated(status));
+
+program.parse();

package/lib/commands/init-all.js

@@ -0,0 +1,247 @@
+/**
+ * init-all command - Initialize all clients from main-config.json
+ *
+ * Usage: ppcos init-all [--force]
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { readFile, mkdir, rename } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validateConfig } from '../utils/validation.js';
+import { calculateChecksum } from '../utils/checksum.js';
+import { createManifest, writeManifest, manifestExists } from '../utils/manifest.js';
+import { getAllFiles, copyFileWithDirs, ensureDir } from '../utils/fs-helpers.js';
+import logger from '../utils/logger.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 config file path
+ * @returns {string}
+ */
+function getConfigPath() {
+  return join(process.cwd(), 'main-config.json');
+}
+
+/**
+ * Get clients directory path from config or default
+ * @param {object} config
+ * @returns {string}
+ */
+function getClientsDir(config) {
+  const dir = config?.settings?.clientsDirectory || 'clients';
+  return join(process.cwd(), dir);
+}
+
+/**
+ * Load and validate main-config.json
+ * @returns {{ config: object, errors: string[] } | null}
+ */
+async function loadConfig() {
+  const configPath = getConfigPath();
+
+  if (!existsSync(configPath)) {
+    return null;
+  }
+
+  try {
+    const content = await readFile(configPath, 'utf8');
+    const config = JSON.parse(content);
+    const validation = validateConfig(config);
+
+    return {
+      config,
+      errors: validation.errors
+    };
+  } catch (err) {
+    return {
+      config: null,
+      errors: [`JSON parse error: ${err.message}`]
+    };
+  }
+}
+
+/**
+ * Create backup of existing client directory
+ * @param {string} clientDir
+ * @returns {Promise<string>} Backup path
+ */
+async function backupClient(clientDir) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupDir = join(clientDir, '.backup', timestamp);
+  const tempBackupDir = join(dirname(clientDir), `.backup-temp-${timestamp}`);
+
+  // Move current contents to temp location
+  await rename(clientDir, tempBackupDir);
+
+  // Create new client directory
+  await mkdir(clientDir, { recursive: true });
+
+  // Move temp to .backup inside new client dir
+  const backupPath = join(clientDir, '.backup', timestamp);
+  await mkdir(join(clientDir, '.backup'), { recursive: true });
+  await rename(tempBackupDir, backupPath);
+
+  return backupPath;
+}
+
+/**
+ * Initialize a single client
+ * @param {string} clientName
+ * @param {string} clientsDir
+ * @param {object} options
+ * @returns {Promise<{ status: 'initialized' | 'skipped' | 'failed', message?: string }>}
+ */
+async function initializeClient(clientName, clientsDir, options = {}) {
+  const clientDir = join(clientsDir, clientName);
+  const basePath = getBaseTemplatePath();
+  const version = getPackageVersion();
+
+  // Check if exists
+  if (existsSync(clientDir)) {
+    if (options.force) {
+      // Backup existing
+      try {
+        await backupClient(clientDir);
+      } catch (err) {
+        return { status: 'failed', message: `Backup failed: ${err.message}` };
+      }
+    } else {
+      return { status: 'skipped', message: 'already exists' };
+    }
+  }
+
+  try {
+    // Copy files and calculate checksums
+    const baseFiles = await getAllFiles(basePath);
+    const managedFiles = {};
+
+    for (const relativePath of baseFiles) {
+      const srcPath = join(basePath, relativePath);
+      const destPath = join(clientDir, relativePath);
+
+      await copyFileWithDirs(srcPath, destPath);
+
+      const checksum = await calculateChecksum(destPath);
+      managedFiles[relativePath] = {
+        checksum,
+        version
+      };
+    }
+
+    // Generate and write .managed.json
+    const manifest = createManifest(version, managedFiles);
+    await writeManifest(clientDir, manifest);
+
+    return { status: 'initialized' };
+  } catch (err) {
+    return { status: 'failed', message: err.message };
+  }
+}
+
+/**
+ * Main init-all command handler
+ * @param {object} options - Command options
+ * @param {boolean} options.force - Reinitialize existing clients
+ */
+export default async function initAll(options = {}) {
+  // 1. Load main-config.json
+  const result = await loadConfig();
+
+  if (result === null) {
+    logger.error('No main-config.json found in current directory.');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (result.errors.length > 0) {
+    logger.error('Invalid main-config.json:');
+    for (const err of result.errors) {
+      console.log(`  - ${err}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const config = result.config;
+  const clientsDir = getClientsDir(config);
+
+  // Filter to enabled clients
+  const enabledClients = config.clients.filter(c => c.enabled);
+
+  if (enabledClients.length === 0) {
+    logger.warn('No enabled clients found in main-config.json');
+    return;
+  }
+
+  console.log(`Found ${enabledClients.length} client${enabledClients.length === 1 ? '' : 's'} in main-config.json`);
+  console.log('');
+
+  // 2. Process each client
+  const results = {
+    initialized: 0,
+    skipped: 0,
+    failed: 0
+  };
+
+  for (const client of enabledClients) {
+    process.stdout.write(`Initializing ${client.name}... `);
+
+    const initResult = await initializeClient(client.name, clientsDir, options);
+
+    if (initResult.status === 'initialized') {
+      logger.success('');
+      results.initialized++;
+    } else if (initResult.status === 'skipped') {
+      console.log(`Skipped (${initResult.message})`);
+      results.skipped++;
+    } else {
+      logger.error(initResult.message || 'Unknown error');
+      results.failed++;
+    }
+  }
+
+  // 3. Display summary
+  console.log('');
+  console.log('Summary:');
+  console.log(`  Initialized: ${results.initialized}`);
+  console.log(`  Skipped: ${results.skipped}`);
+  console.log(`  Failed: ${results.failed}`);
+
+  if (results.failed > 0) {
+    process.exitCode = 1;
+  }
+}
+
+// Export helpers for testing
+export {
+  getPackageVersion,
+  getBaseTemplatePath,
+  getConfigPath,
+  getClientsDir,
+  loadConfig,
+  initializeClient,
+  backupClient
+};