taketomarket 0.1.0

package/bin/lib/health.cjs

@@ -0,0 +1,438 @@
+/**
+ * Health -- Directory integrity validation for ttm-tools.cjs
+ *
+ * Zero npm dependencies. Uses only Node.js built-ins: fs, path.
+ * Depends on: ./core.cjs for output, error, safeReadFile, parseFrontmatter
+ *
+ * Exports: cmdHealth, cmdInit
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { output, safeReadFile, parseFrontmatter } = require('./core.cjs');
+
+/**
+ * Expected reference files in .marketing/ directory.
+ */
+const REFERENCE_FILES = [
+  'POSITIONING.md',
+  'BRAND.md',
+  'ICP.md',
+  'CHANNELS.md',
+  'STATE.md',
+  'CALENDAR.md',
+  'COMPETITORS.md',
+  'METRICS.md',
+  'LEARNINGS.md',
+];
+
+/**
+ * Valid campaign phases for state consistency checking.
+ */
+const VALID_PHASES = new Set([
+  'created', 'researched', 'briefed', 'produced', 'verified',
+  'reviewed', 'fixed', 'shipped', 'measured', 'learned',
+  'archived', 'cancelled',
+]);
+
+/**
+ * Check if a path exists and is a directory.
+ * @param {string} p - Path to check
+ * @returns {boolean}
+ */
+function dirExists(p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a path exists and is a file.
+ * @param {string} p - Path to check
+ * @returns {boolean}
+ */
+function fileExists(p) {
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check campaign STATE.md consistency for all campaigns.
+ * @param {string} campaignsDir - Path to CAMPAIGNS/ directory
+ * @returns {Array} Array of check objects
+ */
+function checkCampaignStateConsistency(campaignsDir) {
+  const checks = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(campaignsDir, { withFileTypes: true });
+  } catch {
+    return checks;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name === 'ARCHIVE') continue;
+    const statePath = path.resolve(campaignsDir, entry.name, 'STATE.md');
+    const content = safeReadFile(statePath);
+    if (content === null) {
+      checks.push({
+        name: `campaign_state_${entry.name}`,
+        status: 'fail',
+        path: `.marketing/CAMPAIGNS/${entry.name}/STATE.md`,
+        detail: 'STATE.md missing',
+      });
+      continue;
+    }
+    const { frontmatter } = parseFrontmatter(content);
+    if (!frontmatter.phase || !VALID_PHASES.has(frontmatter.phase)) {
+      checks.push({
+        name: `campaign_state_${entry.name}`,
+        status: 'fail',
+        path: `.marketing/CAMPAIGNS/${entry.name}/STATE.md`,
+        detail: `invalid phase: ${frontmatter.phase || 'undefined'}`,
+      });
+    } else {
+      checks.push({
+        name: `campaign_state_${entry.name}`,
+        status: 'pass',
+        path: `.marketing/CAMPAIGNS/${entry.name}/STATE.md`,
+      });
+    }
+  }
+  return checks;
+}
+
+/**
+ * Check reference file staleness based on mtime.
+ * @param {string} marketingDir - Path to .marketing/ directory
+ * @param {number} thresholdDays - Days threshold for staleness warning (default 90)
+ * @returns {Array} Array of check objects
+ */
+function checkReferenceStaleness(marketingDir, thresholdDays) {
+  if (!thresholdDays) thresholdDays = 90;
+  const checks = [];
+  const now = Date.now();
+  const thresholdMs = thresholdDays * 24 * 60 * 60 * 1000;
+
+  for (const file of REFERENCE_FILES) {
+    const filePath = path.resolve(marketingDir, file);
+    try {
+      const stat = fs.statSync(filePath);
+      const ageMs = now - stat.mtimeMs;
+      const ageDays = Math.floor(ageMs / (24 * 60 * 60 * 1000));
+      if (ageMs > thresholdMs) {
+        checks.push({
+          name: `staleness_${file.toLowerCase().replace('.md', '')}`,
+          status: 'warn',
+          path: `.marketing/${file}`,
+          detail: `not updated in ${ageDays} days`,
+        });
+      } else {
+        checks.push({
+          name: `staleness_${file.toLowerCase().replace('.md', '')}`,
+          status: 'pass',
+          path: `.marketing/${file}`,
+        });
+      }
+    } catch {
+      // File doesn't exist -- skip (already covered by basic health check)
+    }
+  }
+  return checks;
+}
+
+/**
+ * Check campaign velocity -- detect stuck campaigns.
+ * @param {string} campaignsDir - Path to CAMPAIGNS/ directory
+ * @param {number} thresholdDays - Days threshold for stuck warning (default 14)
+ * @returns {Array} Array of check objects
+ */
+function checkCampaignVelocity(campaignsDir, thresholdDays) {
+  if (!thresholdDays) thresholdDays = 14;
+  const checks = [];
+  const now = Date.now();
+  const thresholdMs = thresholdDays * 24 * 60 * 60 * 1000;
+
+  let entries;
+  try {
+    entries = fs.readdirSync(campaignsDir, { withFileTypes: true });
+  } catch {
+    return checks;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name === 'ARCHIVE') continue;
+    const statePath = path.resolve(campaignsDir, entry.name, 'STATE.md');
+    const content = safeReadFile(statePath);
+    if (content === null) continue;
+    const { frontmatter } = parseFrontmatter(content);
+    const lastUpdated = frontmatter['last_updated'];
+    if (!lastUpdated || lastUpdated === 'null') continue;
+    const lastMs = Date.parse(lastUpdated);
+    if (isNaN(lastMs)) continue;
+    const ageMs = now - lastMs;
+    const ageDays = Math.floor(ageMs / (24 * 60 * 60 * 1000));
+    if (ageMs > thresholdMs) {
+      checks.push({
+        name: `velocity_${entry.name}`,
+        status: 'warn',
+        path: `.marketing/CAMPAIGNS/${entry.name}/STATE.md`,
+        detail: `stuck in ${frontmatter.phase} for ${ageDays} days`,
+      });
+    } else {
+      checks.push({
+        name: `velocity_${entry.name}`,
+        status: 'pass',
+        path: `.marketing/CAMPAIGNS/${entry.name}/STATE.md`,
+      });
+    }
+  }
+  return checks;
+}
+
+/**
+ * Check DRIFT-LOG.md structural integrity.
+ * @param {string} marketingDir - Path to .marketing/ directory
+ * @returns {Array} Array of check objects
+ */
+function checkDriftLogIntegrity(marketingDir) {
+  const checks = [];
+  const driftLogPath = path.resolve(marketingDir, 'DRIFT-LOG.md');
+  const content = safeReadFile(driftLogPath);
+
+  if (content === null) {
+    checks.push({
+      name: 'drift_log_integrity',
+      status: 'warn',
+      path: '.marketing/DRIFT-LOG.md',
+      detail: 'no drift log yet',
+    });
+    return checks;
+  }
+
+  const markerCount = (content.match(/<!-- Audit Trail -->/g) || []).length;
+  if (markerCount === 0) {
+    checks.push({
+      name: 'drift_log_integrity',
+      status: 'fail',
+      path: '.marketing/DRIFT-LOG.md',
+      detail: 'missing audit trail marker',
+    });
+  } else if (markerCount > 1) {
+    checks.push({
+      name: 'drift_log_integrity',
+      status: 'fail',
+      path: '.marketing/DRIFT-LOG.md',
+      detail: 'duplicate audit trail markers',
+    });
+  } else {
+    checks.push({
+      name: 'drift_log_integrity',
+      status: 'pass',
+      path: '.marketing/DRIFT-LOG.md',
+    });
+  }
+  return checks;
+}
+
+/**
+ * Check gate result consistency for campaigns with verification results.
+ * @param {string} campaignsDir - Path to CAMPAIGNS/ directory
+ * @returns {Array} Array of check objects
+ */
+function checkGateConsistency(campaignsDir) {
+  const checks = [];
+  const validGateValues = new Set(['null', 'pass', 'warn', 'fail', 'fix_needed', 'accepted']);
+
+  let entries;
+  try {
+    entries = fs.readdirSync(campaignsDir, { withFileTypes: true });
+  } catch {
+    return checks;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name === 'ARCHIVE') continue;
+    const statePath = path.resolve(campaignsDir, entry.name, 'STATE.md');
+    const content = safeReadFile(statePath);
+    if (content === null) continue;
+    const { frontmatter } = parseFrontmatter(content);
+
+    const invalidGates = [];
+    for (const [key, value] of Object.entries(frontmatter)) {
+      if (key.startsWith('gate.') && value && !validGateValues.has(value)) {
+        invalidGates.push(`${key}=${value}`);
+      }
+    }
+
+    if (invalidGates.length > 0) {
+      checks.push({
+        name: `gate_consistency_${entry.name}`,
+        status: 'fail',
+        path: `.marketing/CAMPAIGNS/${entry.name}/STATE.md`,
+        detail: `invalid gate values: ${invalidGates.join(', ')}`,
+      });
+    } else {
+      checks.push({
+        name: `gate_consistency_${entry.name}`,
+        status: 'pass',
+        path: `.marketing/CAMPAIGNS/${entry.name}/STATE.md`,
+      });
+    }
+  }
+  return checks;
+}
+
+/**
+ * Validate .marketing/ directory structure.
+ *
+ * Checks:
+ * 1. .marketing/ directory exists
+ * 2. .marketing/CAMPAIGNS/ directory exists
+ * 3. Each expected reference file exists
+ * 4. STATE.md has valid frontmatter (parseable)
+ *
+ * When full=true, runs extended checks:
+ * 5. Campaign state consistency
+ * 6. Reference file staleness
+ * 7. Campaign velocity
+ * 8. DRIFT-LOG integrity
+ * 9. Gate result consistency
+ *
+ * healthy = true when .marketing/ and CAMPAIGNS/ both exist and no 'fail' checks.
+ * Reference files use "missing" status (expected before /ttm-init runs).
+ *
+ * @param {boolean} raw - Whether to output raw summary string
+ * @param {boolean} full - Whether to run extended audit checks
+ */
+function cmdHealth(raw, full) {
+  const marketingDir = path.resolve(process.cwd(), '.marketing');
+  const campaignsDir = path.resolve(marketingDir, 'CAMPAIGNS');
+  const checks = [];
+
+  // Check .marketing/ directory
+  const marketingExists = dirExists(marketingDir);
+  checks.push({
+    name: 'marketing_dir',
+    status: marketingExists ? 'pass' : 'fail',
+    path: '.marketing/',
+  });
+
+  // Check CAMPAIGNS/ directory
+  const campaignsExists = dirExists(campaignsDir);
+  checks.push({
+    name: 'campaigns_dir',
+    status: campaignsExists ? 'pass' : 'fail',
+    path: '.marketing/CAMPAIGNS/',
+  });
+
+  // Check each reference file
+  for (const file of REFERENCE_FILES) {
+    const filePath = path.resolve(marketingDir, file);
+    const name = file.toLowerCase().replace('.md', '_md');
+    if (fileExists(filePath)) {
+      // Extra validation for STATE.md -- check frontmatter is parseable
+      if (file === 'STATE.md') {
+        const content = safeReadFile(filePath);
+        const { frontmatter } = parseFrontmatter(content || '');
+        const isValid = Object.keys(frontmatter).length > 0;
+        checks.push({
+          name,
+          status: isValid ? 'pass' : 'fail',
+          path: `.marketing/${file}`,
+          detail: isValid ? undefined : 'frontmatter unparseable',
+        });
+      } else {
+        checks.push({ name, status: 'pass', path: `.marketing/${file}` });
+      }
+    } else {
+      checks.push({ name, status: 'missing', path: `.marketing/${file}` });
+    }
+  }
+
+  // Extended checks when --full flag is passed
+  if (full && campaignsExists) {
+    const stateChecks = checkCampaignStateConsistency(campaignsDir);
+    checks.push(...stateChecks);
+
+    const stalenessChecks = checkReferenceStaleness(marketingDir);
+    checks.push(...stalenessChecks);
+
+    const velocityChecks = checkCampaignVelocity(campaignsDir);
+    checks.push(...velocityChecks);
+
+    const driftChecks = checkDriftLogIntegrity(marketingDir);
+    checks.push(...driftChecks);
+
+    const gateChecks = checkGateConsistency(campaignsDir);
+    checks.push(...gateChecks);
+  }
+
+  const passed = checks.filter(c => c.status === 'pass').length;
+  const total = checks.length;
+  const failures = checks.filter(c => c.status === 'fail').length;
+  // healthy = marketing dir + campaigns dir both exist and no failures
+  const healthy = marketingExists && campaignsExists && failures === 0;
+
+  const result = {
+    healthy,
+    checks,
+    summary: `${passed}/${total} checks passed`,
+  };
+
+  if (raw) {
+    const label = healthy ? 'HEALTHY' : 'UNHEALTHY';
+    const issues = failures;
+    if (healthy) {
+      output(result, true, `${label}: ${passed}/${total} checks passed`);
+    } else {
+      output(result, true, `${label}: ${issues} issue(s) found`);
+    }
+  } else {
+    output(result, false);
+  }
+}
+
+/**
+ * Lightweight init check.
+ * Returns: { initialized, marketing_dir, reference_files_count, total_expected }
+ *
+ * @param {boolean} raw - Whether to output raw summary string
+ */
+function cmdInit(raw) {
+  const marketingDir = path.resolve(process.cwd(), '.marketing');
+  const marketingExists = dirExists(marketingDir);
+
+  let refCount = 0;
+  if (marketingExists) {
+    for (const file of REFERENCE_FILES) {
+      if (fileExists(path.resolve(marketingDir, file))) {
+        refCount++;
+      }
+    }
+  }
+
+  const totalExpected = REFERENCE_FILES.length;
+  const initialized = marketingExists && refCount >= totalExpected;
+
+  const result = {
+    initialized,
+    marketing_dir: marketingExists,
+    reference_files_count: refCount,
+    total_expected: totalExpected,
+  };
+
+  output(result, raw, initialized ? 'initialized' : 'not initialized');
+}
+
+module.exports = {
+  cmdHealth,
+  cmdInit,
+};

package/bin/lib/slug.cjs

@@ -0,0 +1,59 @@
+/**
+ * Slug -- Slug generation and timestamp formatting for ttm-tools.cjs
+ *
+ * Zero npm dependencies. Uses only Node.js built-ins.
+ *
+ * Exports: cmdSlug, cmdTimestamp
+ */
+
+'use strict';
+
+const { output, error } = require('./core.cjs');
+
+/**
+ * Generate a URL-safe slug from text.
+ * Security: /[^a-z0-9]+/g strips all non-alphanumeric characters,
+ * preventing path traversal or injection via slug values.
+ *
+ * @param {string} text - Input text to slugify
+ * @param {boolean} raw - Whether to output raw string
+ */
+function cmdSlug(text, raw) {
+  if (!text || !text.trim()) {
+    error('text required for slug generation');
+  }
+  const slug = text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .substring(0, 60);
+  output({ slug }, raw, slug);
+}
+
+/**
+ * Output a timestamp in the specified format.
+ *
+ * @param {string} format - 'full' (default) | 'date' | 'filename'
+ * @param {boolean} raw - Whether to output raw string
+ */
+function cmdTimestamp(format, raw) {
+  const now = new Date();
+  let result;
+  switch (format) {
+    case 'date':
+      result = now.toISOString().split('T')[0];
+      break;
+    case 'filename':
+      result = now.toISOString().replace(/:/g, '-').replace(/\..+/, '');
+      break;
+    default:
+      result = now.toISOString();
+      break;
+  }
+  output({ timestamp: result }, raw, result);
+}
+
+module.exports = {
+  cmdSlug,
+  cmdTimestamp,
+};

package/bin/lib/state.cjs

@@ -0,0 +1,96 @@
+/**
+ * State -- STATE.md read/update operations for ttm-tools.cjs
+ *
+ * Zero npm dependencies. Uses only Node.js built-ins: path.
+ * Depends on: ./core.cjs for output, error, safeReadFile, safeWriteFile,
+ *             parseFrontmatter, serializeFrontmatter
+ *
+ * Exports: cmdStateRead, cmdStateUpdate
+ */
+
+'use strict';
+
+const path = require('path');
+const {
+  output,
+  error,
+  safeReadFile,
+  safeWriteFile,
+  parseFrontmatter,
+  serializeFrontmatter,
+} = require('./core.cjs');
+
+/**
+ * Resolve and validate the STATE.md path.
+ * Security: uses path.resolve() and rejects paths containing '..' after resolution.
+ * @returns {string} Absolute path to .marketing/STATE.md
+ */
+function resolveStatePath() {
+  const statePath = path.resolve(process.cwd(), '.marketing', 'STATE.md');
+  // Reject paths that escape the project directory
+  const projectRoot = path.resolve(process.cwd());
+  if (!statePath.startsWith(projectRoot)) {
+    error('STATE.md path escapes project directory');
+  }
+  return statePath;
+}
+
+/**
+ * Read .marketing/STATE.md, parse frontmatter, output as JSON.
+ * If STATE.md does not exist, outputs { exists: false, error: "..." }.
+ *
+ * @param {boolean} raw - Whether to output raw string
+ */
+function cmdStateRead(raw) {
+  const statePath = resolveStatePath();
+  const content = safeReadFile(statePath);
+  if (content === null) {
+    output({ exists: false, error: 'STATE.md not found' }, raw, 'STATE.md not found');
+    return;
+  }
+  const { frontmatter, body } = parseFrontmatter(content);
+  const result = {
+    exists: true,
+    ...frontmatter,
+    body_preview: body.substring(0, 200),
+  };
+  output(result, raw, JSON.stringify(frontmatter));
+}
+
+/**
+ * Update a single field in STATE.md frontmatter.
+ * Sets last_updated to current ISO timestamp.
+ *
+ * @param {string} field - Frontmatter field name to update
+ * @param {string} value - New value for the field
+ * @param {boolean} raw - Whether to output raw string
+ */
+function cmdStateUpdate(field, value, raw) {
+  if (!field) error('field name required for state update');
+  if (value === undefined || value === null) error('value required for state update');
+
+  const statePath = resolveStatePath();
+  const content = safeReadFile(statePath);
+  if (content === null) {
+    error('STATE.md not found -- run /ttm-init first');
+  }
+  const { frontmatter, body } = parseFrontmatter(content);
+  const timestamp = new Date().toISOString();
+
+  frontmatter[field] = value;
+  frontmatter['last_updated'] = timestamp;
+
+  const updated = serializeFrontmatter(frontmatter, body);
+  safeWriteFile(statePath, updated);
+
+  output(
+    { updated: field, value, last_updated: timestamp },
+    raw,
+    `${field}=${value}`
+  );
+}
+
+module.exports = {
+  cmdStateRead,
+  cmdStateUpdate,
+};