taketomarket 0.1.0

package/bin/lib/core.cjs

@@ -0,0 +1,172 @@
+/**
+ * Core -- Shared output helpers and utility functions for ttm-tools.cjs
+ *
+ * Zero npm dependencies. Uses only Node.js built-ins: fs, path.
+ *
+ * Exports: output, error, parseNamedArgs, safeReadFile, safeWriteFile,
+ *          parseFrontmatter, serializeFrontmatter
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ── Output helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Write result to stdout. JSON by default, raw string if --raw flag is set.
+ * @param {object} result - Structured result object
+ * @param {boolean} raw - Whether --raw flag was passed
+ * @param {*} rawValue - Plain text value for raw mode
+ */
+function output(result, raw, rawValue) {
+  if (raw && rawValue !== undefined) {
+    process.stdout.write(String(rawValue) + '\n');
+  } else {
+    const json = JSON.stringify(result, null, 2);
+    process.stdout.write(json + '\n');
+  }
+}
+
+/**
+ * Write error message to stderr and exit with code 1.
+ * @param {string} message - Error description
+ */
+function error(message) {
+  process.stderr.write('Error: ' + message + '\n');
+  process.exit(1);
+}
+
+// ── Argument parsing ─────────────────────────────────────────────────────────
+
+/**
+ * Parse --key value pairs from an args array.
+ * Skips --raw (handled globally by router).
+ * @param {string[]} args - Array of CLI arguments
+ * @returns {{ positional: string[], named: object }}
+ */
+function parseNamedArgs(args) {
+  const positional = [];
+  const named = {};
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg === '--raw') {
+      i++;
+      continue;
+    }
+    if (arg.startsWith('--') && i + 1 < args.length) {
+      const key = arg.slice(2);
+      named[key] = args[i + 1];
+      i += 2;
+    } else {
+      positional.push(arg);
+      i++;
+    }
+  }
+  return { positional, named };
+}
+
+// ── File helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Read a file safely. Returns null if file does not exist.
+ * @param {string} filePath - Absolute or relative path
+ * @returns {string|null}
+ */
+function safeReadFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write a file safely. Creates parent directories if needed.
+ * @param {string} filePath - Absolute or relative path
+ * @param {string} content - File content
+ */
+function safeWriteFile(filePath, content) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf-8');
+}
+
+// ── Frontmatter helpers ──────────────────────────────────────────────────────
+
+/**
+ * Parse YAML frontmatter from markdown content.
+ * Handles simple key: value pairs (no nested objects needed for STATE.md).
+ * Returns empty frontmatter object if no frontmatter found.
+ * @param {string} content - Markdown content with optional frontmatter
+ * @returns {{ frontmatter: object, body: string }}
+ */
+function parseFrontmatter(content) {
+  if (!content || !content.startsWith('---')) {
+    return { frontmatter: {}, body: content || '' };
+  }
+  // Normalize line endings before parsing (handles Windows \r\n)
+  const normalized = content.replace(/\r\n/g, '\n');
+  // Match the closing --- only when it occupies a full line (followed by \n or end-of-string)
+  const endMatch = normalized.substring(3).search(/\n---(\n|$)/);
+  if (endMatch === -1) {
+    return { frontmatter: {}, body: content };
+  }
+  const endIndex = endMatch + 3; // adjust for the substring(3) offset
+  const fmBlock = normalized.substring(4, endIndex).trim();
+  const body = normalized.substring(endIndex + 4).trimStart();
+  const frontmatter = {};
+  for (const line of fmBlock.split('\n')) {
+    const colonIndex = line.indexOf(':');
+    if (colonIndex === -1) continue;
+    const key = line.substring(0, colonIndex).trim();
+    let value = line.substring(colonIndex + 1).trim();
+    // Strip surrounding quotes and unescape escaped quotes for round-trip safety
+    if (value.startsWith('"') && value.endsWith('"')) {
+      value = value.slice(1, -1).replace(/\\"/g, '"');
+    } else if (value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    frontmatter[key] = value;
+  }
+  return { frontmatter, body };
+}
+
+/**
+ * Serialize frontmatter object and body back to markdown string.
+ * @param {object} data - Frontmatter key-value pairs
+ * @param {string} body - Markdown body
+ * @returns {string}
+ */
+function serializeFrontmatter(data, body) {
+  const lines = ['---'];
+  for (const [key, value] of Object.entries(data)) {
+    const strVal = String(value);
+    // Quote values that contain special YAML characters
+    if (strVal.includes(':') || strVal.includes('#') || strVal.includes('"') ||
+        strVal.includes('\n') || strVal.includes('\r') ||
+        strVal.startsWith(' ') || strVal.endsWith(' ')) {
+      lines.push(`${key}: "${strVal.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\r/g, '\\r')}"`);
+    } else {
+      lines.push(`${key}: ${strVal}`);
+    }
+  }
+  lines.push('---');
+  lines.push('');
+  if (body) {
+    lines.push(body);
+  }
+  return lines.join('\n');
+}
+
+module.exports = {
+  output,
+  error,
+  parseNamedArgs,
+  safeReadFile,
+  safeWriteFile,
+  parseFrontmatter,
+  serializeFrontmatter,
+};

package/bin/lib/deviation.cjs

@@ -0,0 +1,149 @@
+/**
+ * Deviation -- Append-only deviation log operations for ttm-tools.cjs
+ *
+ * Zero npm dependencies. Uses only Node.js built-ins: path, fs.
+ * Depends on: ./core.cjs for output, error, safeReadFile, safeWriteFile
+ *
+ * Exports: cmdDeviationAppend
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  output,
+  error,
+  safeReadFile,
+  safeWriteFile,
+} = require('./core.cjs');
+
+// Allowlists for validation
+const ALLOWED_GATES = new Set([
+  'positioning_drift', 'claim_accuracy', 'voice_drift',
+  'outcome_alignment', 'funnel_integrity', 'utm_hygiene',
+  'compliance', 'competitor_collision', 'icp_fit',
+  'format_correctness',
+]);
+
+const ALLOWED_RESULTS = new Set(['accepted', 'correct', 'escalated']);
+
+/**
+ * Sanitize justification text to prevent injection.
+ * Strips backticks, all $ signs, newlines, pipe chars, and redirects.
+ * @param {string} text - Raw justification
+ * @returns {string} Sanitized text (max 100 chars)
+ */
+function sanitizeJustification(text) {
+  if (!text) return '';
+  return text
+    .replace(/`/g, "'")
+    .replace(/\$/g, '')
+    .replace(/\n/g, ' ')
+    .replace(/\r/g, '')
+    .replace(/\|/g, '-')
+    .replace(/[<>]/g, '')
+    .substring(0, 100)
+    .trim();
+}
+
+/**
+ * Append a deviation entry to a campaign's DEVIATIONS.md.
+ *
+ * @param {string} slug - Campaign slug
+ * @param {string} gate - Gate name (must be in ALLOWED_GATES)
+ * @param {string} result - Deviation result (accepted, correct, escalated)
+ * @param {string} justification - User justification text
+ * @param {string} asset - Asset filename
+ * @param {boolean} raw - Whether to output raw string
+ * @param {object} [extra] - Additional named fields: gate_id, tier, finding, action, run
+ */
+function cmdDeviationAppend(slug, gate, result, justification, asset, raw, extra) {
+  if (!slug || !slug.trim()) error('slug required for deviation append');
+  if (!gate || !gate.trim()) error('gate required for deviation append');
+  if (!result || !result.trim()) error('result required for deviation append');
+  if (!asset || !asset.trim()) error('asset required for deviation append');
+
+  // Validate slug via path.resolve to prevent traversal
+  const safe = slug.toLowerCase().replace(/[^a-z0-9-]/g, '');
+  const projectRoot = path.resolve(process.cwd());
+  const campaignDir = path.resolve(projectRoot, '.marketing', 'CAMPAIGNS', safe);
+  if (!campaignDir.startsWith(projectRoot)) {
+    error('campaign path escapes project directory');
+  }
+
+  // Validate gate name against allowlist
+  const gateLower = gate.toLowerCase().trim();
+  if (!ALLOWED_GATES.has(gateLower)) {
+    error(`Unknown gate: ${gate}. Allowed: ${[...ALLOWED_GATES].join(', ')}`);
+  }
+
+  // Validate result against allowlist
+  const resultLower = result.toLowerCase().trim();
+  if (!ALLOWED_RESULTS.has(resultLower)) {
+    error(`Unknown result: ${result}. Allowed: ${[...ALLOWED_RESULTS].join(', ')}`);
+  }
+
+  const deviationsPath = path.resolve(campaignDir, 'DEVIATIONS.md');
+  const safeAsset = asset.replace(/\|/g, '-').replace(/\n/g, '').substring(0, 80);
+  const safeJustification = sanitizeJustification(justification || '');
+  const timestamp = new Date().toISOString();
+
+  // Atomically create DEVIATIONS.md if it does not exist (prevents TOCTOU race)
+  const templatePath = path.resolve(__dirname, '..', '..', 'templates', 'deviation-log.md');
+  const template = safeReadFile(templatePath);
+  const initialContent = template
+    ? template.replace(/\[SLUG\]/g, safe).replace(/\[ISO_TIMESTAMP\]/g, timestamp)
+    : [
+        '# Deviation Log',
+        '',
+        `**Campaign:** ${safe}`,
+        `**Created:** ${timestamp}`,
+        '',
+        '| Timestamp | Gate | Tier | Result | Asset | Finding | Action | Justification | Verify Run |',
+        '|-----------|------|------|--------|-------|---------|--------|---------------|------------|',
+        '<!-- NEW ENTRIES BELOW THIS LINE -->',
+      ].join('\n');
+  try {
+    fs.writeFileSync(deviationsPath, initialContent, { flag: 'wx', encoding: 'utf-8' });
+  } catch (e) {
+    if (e.code !== 'EEXIST') throw e;
+    // File already exists -- proceed to append
+  }
+
+  // Read current content and append new entry
+  const content = safeReadFile(deviationsPath);
+  if (content === null) {
+    error(`Failed to read DEVIATIONS.md for campaign: ${safe}`);
+  }
+
+  // Build table row entry
+  const opts = extra || {};
+  const tierMap = {
+    positioning_drift: 'T1', claim_accuracy: 'T1', voice_drift: 'T2',
+    outcome_alignment: 'T1', funnel_integrity: 'T2', utm_hygiene: 'T2',
+    compliance: 'T2', competitor_collision: 'T2', icp_fit: 'T2',
+    format_correctness: 'T2',
+  };
+  const tier = (opts.tier || tierMap[gateLower] || 'T2').toString().substring(0, 10);
+  const actionMap = { accepted: 'Accept+log', correct: 'Correct', escalated: 'Escalate' };
+  const action = sanitizeJustification(opts.action || '') || actionMap[resultLower] || resultLower;
+  const finding = sanitizeJustification(opts.finding || '') || '--';
+  const run = (opts.run || '--').toString().replace(/\|/g, '-').substring(0, 20);
+
+  const newRow = `| ${timestamp} | ${gateLower} | ${tier} | ${resultLower} | ${safeAsset} | ${finding} | ${action} | ${safeJustification} | ${run} |`;
+
+  // Append after the last line of content
+  const updated = content.trimEnd() + '\n' + newRow + '\n';
+  safeWriteFile(deviationsPath, updated);
+
+  output(
+    { appended: true, gate: gateLower, result: resultLower, asset: safeAsset, timestamp },
+    raw,
+    `appended ${gateLower}=${resultLower}`
+  );
+}
+
+module.exports = {
+  cmdDeviationAppend,
+};

package/bin/lib/drift-log.cjs

@@ -0,0 +1,219 @@
+/**
+ * Drift Log -- Append-only DRIFT-LOG.md operations for ttm-tools.cjs
+ *
+ * Zero npm dependencies. Uses only Node.js built-ins: path, fs.
+ * Depends on: ./core.cjs for output, error, safeReadFile, safeWriteFile
+ *
+ * Exports: cmdDriftLogAppend, cmdDriftLogDeprecation
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  output,
+  error,
+  safeReadFile,
+  safeWriteFile,
+} = require('./core.cjs');
+
+// Allowlist for event types
+const ALLOWED_EVENT_TYPES = new Set(['shift', 'audit', 'deviation']);
+
+/**
+ * Sanitize details text to prevent injection.
+ * Strips backticks, all $ signs, newlines, pipe chars, and redirects.
+ * @param {string} text - Raw details text
+ * @returns {string} Sanitized text (max 200 chars)
+ */
+function sanitizeDetails(text) {
+  if (!text) return '';
+  return text
+    .replace(/`/g, "'")
+    .replace(/\$/g, '')
+    .replace(/\n/g, ' ')
+    .replace(/\r/g, '')
+    .replace(/\|/g, '-')
+    .replace(/[<>]/g, '')
+    .substring(0, 200)
+    .trim();
+}
+
+/**
+ * Resolve the DRIFT-LOG.md path and ensure it is inside the project root.
+ * @returns {{ driftLogPath: string, projectRoot: string }}
+ */
+function resolveDriftLogPath() {
+  const projectRoot = path.resolve(process.cwd());
+  const driftLogPath = path.resolve(process.cwd(), '.marketing', 'DRIFT-LOG.md');
+  if (!driftLogPath.startsWith(projectRoot)) {
+    error('DRIFT-LOG.md path escapes project directory');
+  }
+  return { driftLogPath, projectRoot };
+}
+
+/**
+ * Ensure DRIFT-LOG.md exists using TOCTOU-safe atomic creation.
+ * @param {string} driftLogPath - Absolute path to DRIFT-LOG.md
+ */
+function ensureDriftLog(driftLogPath) {
+  const timestamp = new Date().toISOString();
+  const templatePath = path.resolve(__dirname, '..', '..', 'templates', 'drift-log.md');
+  const template = safeReadFile(templatePath);
+  const initialContent = template
+    ? template.replace(/\[ISO_TIMESTAMP\]/g, timestamp)
+    : [
+        '# Positioning Drift Log',
+        '',
+        `**Created:** ${timestamp}`,
+        '',
+        'This file is **append-only**.',
+        '',
+        '## Audit Trail',
+        '',
+        '| Date | Event | Source | Details | Assets Affected |',
+        '|------|-------|--------|---------|-----------------|',
+        '<!-- NEW ENTRIES BELOW THIS LINE -->',
+        '',
+        '## Deprecation Backlog',
+        '',
+        '| Asset | Campaign | Old Positioning Element | Required Update | Deadline | Status |',
+        '|-------|----------|------------------------|-----------------|----------|--------|',
+        '<!-- DEPRECATION ENTRIES BELOW THIS LINE -->',
+      ].join('\n');
+
+  // Ensure .marketing directory exists
+  const dir = path.dirname(driftLogPath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  try {
+    fs.writeFileSync(driftLogPath, initialContent, { flag: 'wx', encoding: 'utf-8' });
+  } catch (e) {
+    if (e.code !== 'EEXIST') throw e;
+    // File already exists -- proceed to append
+  }
+}
+
+/**
+ * Append a drift event entry to .marketing/DRIFT-LOG.md.
+ *
+ * @param {string} eventType - Event type (shift, audit, deviation)
+ * @param {string} source - Source command or campaign that triggered the event
+ * @param {string} details - Details/summary text
+ * @param {string|number} affectedCount - Number of assets affected
+ * @param {boolean} raw - Whether to output raw string
+ */
+function cmdDriftLogAppend(eventType, source, details, affectedCount, raw) {
+  if (!eventType || !eventType.trim()) error('event-type required for drift-log append');
+  if (!source || !source.trim()) error('source required for drift-log append');
+
+  // Validate event type against allowlist
+  const eventLower = eventType.toLowerCase().trim();
+  if (!ALLOWED_EVENT_TYPES.has(eventLower)) {
+    error(`Unknown event type: ${eventType}. Allowed: ${[...ALLOWED_EVENT_TYPES].join(', ')}`);
+  }
+
+  // Sanitize inputs
+  const safeSource = source.replace(/\|/g, '-').replace(/\n/g, '').replace(/[<>]/g, '').substring(0, 80);
+  const safeDetails = sanitizeDetails(details || '');
+  const safeAffected = parseInt(affectedCount, 10) || 0;
+
+  const { driftLogPath } = resolveDriftLogPath();
+
+  // TOCTOU defense: create if not exists
+  ensureDriftLog(driftLogPath);
+
+  // Read current content and append new entry
+  const content = safeReadFile(driftLogPath);
+  if (content === null) {
+    error('Failed to read DRIFT-LOG.md');
+  }
+
+  const timestamp = new Date().toISOString();
+  const newRow = `| ${timestamp} | ${eventLower} | ${safeSource} | ${safeDetails} | ${safeAffected} |`;
+
+  // Find the Audit Trail marker and append after it
+  const marker = '<!-- NEW ENTRIES BELOW THIS LINE -->';
+  let updated;
+  const markerCount = content.split(marker).length - 1;
+  if (markerCount > 1) {
+    error(`DRIFT-LOG.md has ${markerCount} occurrences of the Audit Trail marker. File may be corrupted.`);
+  }
+  if (markerCount === 1) {
+    updated = content.replace(marker, marker + '\n' + newRow);
+  } else {
+    // Fallback: append at end of content
+    updated = content.trimEnd() + '\n' + newRow + '\n';
+  }
+
+  safeWriteFile(driftLogPath, updated);
+
+  output(
+    { appended: true, event_type: eventLower, source: safeSource, timestamp },
+    raw,
+    'appended ' + eventLower + '=' + safeSource
+  );
+}
+
+/**
+ * Append a deprecation entry to .marketing/DRIFT-LOG.md Deprecation Backlog.
+ *
+ * @param {string} asset - Asset identifier
+ * @param {string} campaign - Campaign slug
+ * @param {string} oldElement - Old positioning element being deprecated
+ * @param {string} requiredUpdate - Description of required update
+ * @param {string} deadline - Deadline for the update (ISO date or description)
+ * @param {boolean} raw - Whether to output raw string
+ */
+function cmdDriftLogDeprecation(asset, campaign, oldElement, requiredUpdate, deadline, raw) {
+  if (!asset || !asset.trim()) error('asset required for drift-log deprecation');
+  if (!campaign || !campaign.trim()) error('campaign required for drift-log deprecation');
+
+  // Sanitize all inputs
+  const safeAsset = (asset || '').replace(/\|/g, '-').replace(/\n/g, '').replace(/[<>]/g, '').substring(0, 80);
+  const safeCampaign = (campaign || '').replace(/\|/g, '-').replace(/\n/g, '').replace(/[<>]/g, '').substring(0, 80);
+  const safeOldElement = sanitizeDetails(oldElement || '');
+  const safeUpdate = sanitizeDetails(requiredUpdate || '');
+  const safeDeadline = (deadline || '').replace(/\|/g, '-').replace(/\n/g, '').replace(/[<>]/g, '').substring(0, 30);
+
+  const { driftLogPath } = resolveDriftLogPath();
+
+  // TOCTOU defense: create if not exists
+  ensureDriftLog(driftLogPath);
+
+  // Read current content and append deprecation entry
+  const content = safeReadFile(driftLogPath);
+  if (content === null) {
+    error('Failed to read DRIFT-LOG.md');
+  }
+
+  const newRow = `| ${safeAsset} | ${safeCampaign} | ${safeOldElement} | ${safeUpdate} | ${safeDeadline} | pending |`;
+
+  // Find the Deprecation Backlog marker and append after it
+  const marker = '<!-- DEPRECATION ENTRIES BELOW THIS LINE -->';
+  let updated;
+  const markerCount = content.split(marker).length - 1;
+  if (markerCount > 1) {
+    error(`DRIFT-LOG.md has ${markerCount} occurrences of the Deprecation marker. File may be corrupted.`);
+  }
+  if (markerCount === 1) {
+    updated = content.replace(marker, marker + '\n' + newRow);
+  } else {
+    // Fallback: append at end of content
+    updated = content.trimEnd() + '\n' + newRow + '\n';
+  }
+
+  safeWriteFile(driftLogPath, updated);
+
+  output(
+    { appended: true, asset: safeAsset, deadline: safeDeadline },
+    raw,
+    'deprecation added'
+  );
+}
+
+module.exports = {
+  cmdDriftLogAppend,
+  cmdDriftLogDeprecation,
+};