scc-universal 1.1.0

package/scripts/lib/utils.js

@@ -0,0 +1,313 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Read a JSON file safely, returning null on error.
+ */
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      process.stderr.write(`[SCC] readJson failed for ${filePath}: ${err.message}\n`);
+    }
+    return null;
+  }
+}
+
+/**
+ * Check if a file exists.
+ */
+function fileExists(filePath) {
+  try {
+    fs.accessSync(filePath, fs.constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ensure a directory exists (mkdir -p).
+ */
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+/**
+ * Copy a file, creating parent directories as needed.
+ */
+function copyFile(src, dest) {
+  ensureDir(path.dirname(dest));
+  fs.copyFileSync(src, dest);
+}
+
+/**
+ * Get the SCC plugin root directory.
+ */
+function getPluginRoot() {
+  return process.env.CLAUDE_PLUGIN_ROOT || process.env.SCC_PLUGIN_ROOT || path.join(__dirname, '..', '..');
+}
+
+/**
+ * Parse YAML frontmatter from a markdown file.
+ * Returns { frontmatter: Object, body: string }.
+ *
+ * Supports:
+ *   - Simple scalars:       key: value
+ *   - Quoted strings:       key: "value"  or  key: 'value'
+ *   - Booleans:             key: true  /  key: false  (returned as JS boolean)
+ *   - Inline arrays:        key: ["a", "b"]  or  key: [a, b]
+ *   - Folded block scalar:  key: >-   (multi-line, joined with spaces, trailing newline stripped)
+ *   - Folded block scalar:  key: >    (multi-line, joined with spaces, trailing newline kept)
+ *   - Literal block scalar: key: |-   (multi-line, newlines preserved, trailing newline stripped)
+ *   - Literal block scalar: key: |    (multi-line, newlines preserved, trailing newline kept)
+ *
+ * The old implementation parsed line-by-line and returned the literal string ">-" for
+ * block scalar keys, silently discarding the actual multi-line content. This version
+ * collects all indented continuation lines and folds/preserves them correctly.
+ */
+function parseFrontmatter(content) {
+  // Normalise CRLF → LF for Windows compatibility
+  const normalised = content.replace(/\r\n/g, '\n');
+  const match = normalised.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+
+  if (!match) return { frontmatter: {}, body: content };
+
+  const frontmatter = {};
+  const yamlLines = match[1].split('\n');
+  let i = 0;
+
+  while (i < yamlLines.length) {
+    const line = yamlLines[i];
+    const colonIdx = line.indexOf(':');
+
+    // Skip blank lines and lines without a colon
+    if (colonIdx === -1 || line.trim() === '') { i++; continue; }
+
+    const key = line.slice(0, colonIdx).trim();
+    const raw = line.slice(colonIdx + 1).trim();
+
+    if (!key) { i++; continue; }
+
+    // ── YAML block scalar: >-, >, |-, | ──────────────────────────────────────
+    // When the value is a block indicator the actual content is on the
+    // following indented lines.
+    if (raw === '>-' || raw === '>' || raw === '|-' || raw === '|') {
+      const isFolded = raw === '>' || raw === '>-';
+      const stripFinal = raw === '>-' || raw === '|-';
+
+      const blockLines = [];
+      i++;
+
+      while (i < yamlLines.length) {
+        const next = yamlLines[i];
+        // Block content: indented with at least one space or tab
+        if (next.startsWith(' ') || next.startsWith('\t')) {
+          blockLines.push(next.trim());
+          i++;
+        } else if (next.trim() === '') {
+          // Blank lines inside a block scalar are allowed — preserve as paragraph break
+          blockLines.push('');
+          i++;
+        } else {
+          break; // Non-indented line signals end of block
+        }
+      }
+
+      // Remove leading/trailing empty strings caused by blank lines at block edges
+      while (blockLines.length > 0 && blockLines[0] === '') blockLines.shift();
+      while (blockLines.length > 0 && blockLines[blockLines.length - 1] === '') blockLines.pop();
+
+      let value;
+      if (isFolded) {
+        // Folded (>): join lines with a single space, collapsing internal whitespace
+        value = blockLines
+          .join(' ')
+          .replace(/\s{2,}/g, ' ')
+          .trim();
+      } else {
+        // Literal (|): preserve newlines exactly
+        value = blockLines.join('\n');
+        if (stripFinal) value = value.replace(/\n+$/, '');
+      }
+
+      frontmatter[key] = value;
+      continue;
+    }
+
+    // ── Inline array ─────────────────────────────────────────────────────────
+    if (raw.startsWith('[') && raw.endsWith(']')) {
+      frontmatter[key] = raw
+        .slice(1, -1)
+        .split(',')
+        .map(v => v.trim().replace(/^["']|["']$/g, ''))
+        .filter(Boolean);
+      i++;
+      continue;
+    }
+
+    // ── Plain string (remove surrounding quotes) ──────────────────────────────
+    // NOTE: true/false are intentionally kept as strings ("true"/"false") for
+    // backward compatibility — all existing callers use string comparison.
+    // Use parseBool(frontmatter[key]) when you need an actual boolean.
+    frontmatter[key] = raw.replace(/^["']|["']$/g, '');
+    i++;
+  }
+
+  return { frontmatter, body: match[2] };
+}
+
+/**
+ * Recursively list all files under a directory.
+ * Returns an array of absolute paths.
+ */
+function listFilesRecursive(dir) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...listFilesRecursive(full));
+    } else {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/**
+ * Compute a simple hash (used for drift detection).
+ * Returns a hex string based on file content length + first 512 bytes.
+ */
+function simpleHash(filePath) {
+  try {
+    const buf = fs.readFileSync(filePath);
+    let hash = buf.length;
+    const sample = buf.slice(0, 512);
+    for (let i = 0; i < sample.length; i++) {
+      hash = ((hash << 5) - hash + sample[i]) & 0xffffffff;
+    }
+    return (hash >>> 0).toString(16).padStart(8, '0');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read a text file safely, returning null on error.
+ */
+function readFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      process.stderr.write(`[SCC] readFile failed for ${filePath}: ${err.message}\n`);
+    }
+    return null;
+  }
+}
+
+/**
+ * Count regex matches in a file.
+ */
+function countInFile(filePath, pattern) {
+  const content = readFile(filePath);
+  if (content === null) return 0;
+
+  let regex;
+  try {
+    if (pattern instanceof RegExp) {
+      regex = new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : pattern.flags + 'g');
+    } else if (typeof pattern === 'string') {
+      regex = new RegExp(pattern, 'g');
+    } else {
+      return 0;
+    }
+  } catch {
+    return 0;
+  }
+  const matches = content.match(regex);
+  return matches ? matches.length : 0;
+}
+
+/**
+ * Safely coerce a frontmatter boolean field to a JS boolean.
+ *
+ * parseFrontmatter returns ALL values as strings for backward compatibility.
+ * Use this helper whenever you need an actual boolean from a frontmatter field:
+ *
+ *   parseBool(frontmatter['user-invocable'])   // → true | false | undefined
+ *
+ * Returns undefined (not false) when value is absent, so callers can
+ * distinguish "not set" from "explicitly false".
+ */
+function parseBool(value) {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === 'boolean') return value;
+  const s = String(value).trim().toLowerCase();
+  if (s === 'true') return true;
+  if (s === 'false') return false;
+  return undefined;
+}
+
+/**
+ * Serialize a frontmatter object and body back into a markdown string.
+ *
+ * Multi-line string values (containing \n or longer than 80 chars) are
+ * written as YAML folded block scalars (>-) so they round-trip correctly
+ * through parseFrontmatter.
+ */
+function serializeFrontmatter(frontmatter, body) {
+  const keys = Object.keys(frontmatter);
+  if (keys.length === 0) return body;
+
+  const lines = [];
+  for (const key of keys) {
+    const value = frontmatter[key];
+    if (value === undefined || value === null) continue;
+
+    if (Array.isArray(value)) {
+      lines.push(`${key}: [${value.map(v => `"${v}"`).join(', ')}]`);
+    } else if (typeof value === 'boolean') {
+      lines.push(`${key}: ${value}`);
+    } else if (typeof value === 'string' && (value.includes('\n') || value.length > 80)) {
+      // Use folded block scalar for long or multi-line strings
+      const indented = value
+        .split('\n')
+        .map(l => `  ${l}`)
+        .join('\n');
+      lines.push(`${key}: >-\n${indented}`);
+    } else {
+      lines.push(`${key}: ${value}`);
+    }
+  }
+
+  return `---\n${lines.join('\n')}\n---\n${body}`;
+}
+
+/**
+ * Log to stderr (visible in Claude Code output, not captured as tool result).
+ */
+function log(message) {
+  console.error(message);
+}
+
+module.exports = {
+  readJson,
+  readFile,
+  fileExists,
+  ensureDir,
+  copyFile,
+  getPluginRoot,
+  parseFrontmatter,
+  parseBool,
+  serializeFrontmatter,
+  listFilesRecursive,
+  simpleHash,
+  countInFile,
+  log,
+};

package/scripts/scc.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+const COMMANDS = {
+  install: { script: 'cli/install-apply.js', description: 'Install SCC content into a supported target (apex, lwc, all)' },
+  plan: { script: 'dev/install-plan.js', description: 'Inspect selective-install manifests' },
+  'list-installed': { script: 'dev/list-installed.js', description: 'List currently installed SCC content' },
+  doctor: { script: 'dev/doctor.js', description: 'Diagnose missing or drifted files' },
+  repair: { script: 'dev/repair.js', description: 'Restore drifted files' },
+  status: { script: 'dev/status.js', description: 'Query JSON state store' },
+  sessions: { script: 'dev/sessions-cli.js', description: 'List or inspect sessions' },
+  'session-inspect': { script: 'dev/session-inspect.js', description: 'Emit canonical SCC session snapshots from dmux or Claude history targets' },
+  uninstall: { script: 'cli/uninstall.js', description: 'Remove SCC-managed files' },
+};
+
+const PRIMARY_COMMANDS = ['install', 'plan', 'list-installed', 'doctor', 'repair', 'status', 'sessions', 'session-inspect', 'uninstall'];
+
+function showHelp(exitCode = 0) {
+  console.log(`
+SCC — Salesforce Claude Code CLI
+
+Usage:
+  scc <command> [args...]
+  scc [install args...]
+
+Commands:
+${PRIMARY_COMMANDS.map(cmd => `  ${cmd.padEnd(18)} ${COMMANDS[cmd].description}`).join('\n')}
+
+Compatibility:
+  scc [args...]      Without a command, args are routed to "install"
+  scc help <command> Show help for a specific command
+
+Install targets:
+  apex              Install Apex development content
+  lwc               Install LWC development content
+  all               Install everything
+
+Install profiles:
+  --profile apex       Apex development suite (core + apex + platform + devops + security)
+  --profile lwc        LWC development suite (core + lwc + platform + devops + security)
+  --profile full       Complete suite — all 7 bundles (default)
+
+Examples:
+  scc apex
+  scc all
+  scc install --config scc-install.json
+  scc install --profile apex --target claude
+  scc plan --config scc-install.json --target cursor
+  scc doctor
+  scc repair --dry-run
+  scc status --json
+  scc sessions
+  scc session-inspect claude:latest
+  scc uninstall --dry-run
+
+Environment:
+  SCC_HOOK_PROFILE    Hook profile: minimal | standard | strict
+  SCC_DISABLED_HOOKS  Comma-separated list of hooks to disable
+  SF_ORG_ALIAS        Default Salesforce org alias
+
+Documentation: https://github.com/jiten-singh-shahi/salesforce-claude-code
+`);
+  process.exit(exitCode);
+}
+
+function resolveCommand(argv) {
+  const args = argv.slice(2);
+  if (args.length === 0) return { mode: 'help' };
+
+  const [firstArg, ...restArgs] = args;
+
+  if (firstArg === '--help' || firstArg === '-h') return { mode: 'help' };
+  if (firstArg === '--version' || firstArg === '-v') return { mode: 'version' };
+
+  if (firstArg === 'help') {
+    return { mode: 'help-command', command: restArgs[0] || null };
+  }
+
+  if (COMMANDS[firstArg]) {
+    return { mode: 'delegate', command: firstArg, args: restArgs };
+  }
+
+  // Treat as install target shorthand
+  return { mode: 'delegate', command: 'install', args };
+}
+
+function runCommand(commandName, args) {
+  const command = COMMANDS[commandName];
+  if (!command) {
+    throw new Error(`Unknown command: ${commandName}`);
+  }
+
+  const result = spawnSync(
+    process.execPath,
+    [path.join(__dirname, command.script), ...args],
+    {
+      cwd: process.cwd(),
+      env: { ...process.env, CLAUDE_PLUGIN_ROOT: path.join(__dirname, '..'), SCC_PLUGIN_ROOT: path.join(__dirname, '..') },
+      encoding: 'utf8',
+      maxBuffer: 10 * 1024 * 1024,
+    }
+  );
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  if (result.stdout) {
+    process.stdout.write(result.stdout);
+  }
+
+  if (result.stderr) {
+    process.stderr.write(result.stderr);
+  }
+
+  if (typeof result.status === 'number') {
+    return result.status;
+  }
+
+  if (result.signal) {
+    throw new Error(`Command "${commandName}" terminated by signal ${result.signal}`);
+  }
+
+  return 1;
+}
+
+function main() {
+  try {
+    const resolved = resolveCommand(process.argv);
+
+    if (resolved.mode === 'help') {
+      showHelp(0);
+    }
+
+    if (resolved.mode === 'version') {
+      const pkg = require('../package.json');
+      console.log(pkg.version);
+      process.exit(0);
+    }
+
+    if (resolved.mode === 'help-command') {
+      if (!resolved.command) {
+        showHelp(0);
+      }
+
+      if (!COMMANDS[resolved.command]) {
+        throw new Error(`Unknown command: ${resolved.command}`);
+      }
+
+      process.exitCode = runCommand(resolved.command, ['--help']);
+      return;
+    }
+
+    process.exitCode = runCommand(resolved.command, resolved.args);
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/skills/_reference/AGENTFORCE_PATTERNS.md

@@ -0,0 +1,112 @@
+# Agentforce Patterns — Reference
+
+> Source: <https://developer.salesforce.com/docs/ai/agentforce/guide/get-started-actions.html>
+> Also: <https://developer.salesforce.com/blogs/2025/07/best-practices-for-building-agentforce-apex-actions>
+> Also: <https://developer.salesforce.com/blogs/2025/01/how-to-write-effective-natural-language-instructions-for-agentforce>
+> Last verified: API v66.0, Spring '26 (2026-03-28)
+
+## Architecture
+
+```
+Agent
+ +-- Topic (job-to-be-done container, e.g. "Order Management")
+ |    +-- Classification Description (routes user queries to this topic)
+ |    +-- Scope (what the agent WILL and WILL NOT do)
+ |    +-- Instructions (numbered guidelines for agent behavior)
+ |    +-- Actions (1..N tools the agent can invoke)
+ |         +-- Action Instructions (purpose, goal, scope)
+ |         +-- Input Parameters (with input instructions)
+ |         +-- Output Parameters (with output instructions)
+ +-- Topic ...
+```
+
+**Recommended limits**: max 10 topics per agent; 12-15 actions per topic. Exceeding causes context confusion in the Atlas reasoning engine.
+
+## Action Types
+
+| Action Source | How It Works | When to Use |
+|---|---|---|
+| **Apex `@InvocableMethod`** | Annotated static method exposed to Agentforce Builder | Custom business logic, DML, callouts |
+| **Apex REST** | `@RestResource` class registered via API catalog | External API wrappers |
+| **AuraEnabled** | `@AuraEnabled` controller method with OpenAPI doc | Reusing existing LWC controller logic |
+| **Autolaunched Flow** | Flow with no screens; invoked as action | Declarative orchestration, record ops |
+| **Prompt Template** | Flex prompt template from Prompt Builder | LLM-generated text, summaries, classification |
+| **Named Query (Beta)** | Custom SOQL exposed as action | Read-only data retrieval |
+| **MCP Server** | External tool via Model Context Protocol | Third-party integrations |
+
+All action types support enhancement via: Lightning Types (rich UI), Global Copy, Apex Citations (knowledge articles, PDFs, external URLs).
+
+## Apex Action Rules
+
+| Rule | Detail |
+|---|---|
+| Annotation | `@InvocableMethod(label='...' description='...')` on a `public static` method |
+| Sharing | Always use `with sharing`; run DML/queries in `with user` mode |
+| Bulkification | Actions do NOT bulkify by default; each executes in its own transaction |
+| Error handling | Use `try-catch`; return user-friendly messages; use `Database` class for partial processing |
+| Decomposition | Break complex actions into smaller ones to avoid CPU timeout (10s sync limit) |
+| Async work | Use Queueable Apex for long-running tasks; return a requestId for status tracking |
+| Labels | Keep Apex `label`/`description` in sync with Agentforce Builder action config |
+
+## Instruction Guidelines
+
+| Instruction Type | Rules |
+|---|---|
+| **Topic Classification** | Concise; describes what queries route here. E.g. "Manages customer inquiries about order status and returns." |
+| **Topic Scope** | Explicit WILL/WILL NOT. E.g. "Handle resending confirmations, but do not create new reservations." |
+| **Topic Instructions** | Numbered list in a single box. Positive framing ("always do X" not "don't do Y"). No deterministic business rules here -- put those in action code. |
+| **Action Instructions** | 1-3 sentences: purpose, goal, scope. Specify dependent actions. Use varied verb names across actions. |
+| **Input Instructions** | Specify field name, data type, format. E.g. "accountId -- The 18-digit unique Account record ID" |
+| **Output Instructions** | Describe return value with type. E.g. "balance: numeric value representing current account balance" |
+
+**Anti-patterns**: Overusing "must"/"never"/"always" (agent gets stuck); relying on topic instructions for input validation (use action code); similar action names like "Get Project Details" vs "Get Task Details" (use varied verbs: "Locate" vs "Retrieve").
+
+## Agent Script (Agentforce Builder)
+
+Agent Script combines natural language instructions with programmatic expressions.
+
+| Element | Purpose |
+|---|---|
+| Instructions | LLM reasoning areas (non-deterministic) |
+| Expressions | If/else conditions, transitions, variable ops (deterministic) |
+| Variables | Store conversation state; prevent context window overflow |
+| `@` references | Link to actions and topics in Canvas view |
+| `/` shortcut | Insert expressions in Canvas view |
+| Topic pass-through | Chain actions across topics; deterministic or LLM-controlled |
+
+Development surfaces: Canvas View (visual blocks), Script View (syntax highlighting + autocomplete), Agentforce DX (local VS Code with `sf agent` CLI).
+
+## Invocation Channels
+
+| Channel | Method |
+|---|---|
+| Flow | Standard "AI Agent" action in Flow Builder; pass user message + optional session ID |
+| Apex | Invocable Action API with agent API name; REST-exposable |
+| LWC | Via Apex method call |
+| External systems | REST with OAuth 2.0 (Web-Server or User-Agent flow) |
+| Agent-to-agent | Flow-based agent action invocation |
+| Slack, websites, apps | Deploy via Agentforce channel configuration |
+
+Session ID ties multi-turn conversations together. First message generates the ID; pass it with subsequent messages.
+
+## Testing
+
+| Tool | Purpose |
+|---|---|
+| **Agent Builder Preview** | Real-time conversational testing with context simulation (language, app, page, record) |
+| **Agentforce Testing Center** | Bulk test execution; auto-generates test cases from knowledge base content |
+| **Agentforce DX CLI** | `sf agent generate test-spec` (YAML), `sf agent test create`, `sf agent test run` |
+| **VS Code Agent Panel** | View/run tests; Agent Preview pane for conversations; Apex Replay Debugger for actions |
+| **Testing API** | REST API + Connect API for programmatic test execution |
+| **Apex unit tests** | Standard `@isTest` for action implementation code |
+
+DX test workflow: generate YAML spec -> customize test cases -> create in org -> run -> integrate into CI pipeline.
+
+## Context Engineering Principles
+
+1. Limit topics (max 10) and actions per topic (12-15) to avoid context confusion
+2. Use variables to store key facts instead of relying on conversation memory
+3. Eliminate contradictions across topic instructions, action instructions, and scope definitions
+4. Validate RAG/knowledge data is current and accurate
+5. Use structured actions for critical business logic; reserve natural language for conversational tasks
+6. Four failure modes to watch: context distraction, context clash, context poisoning, context confusion