@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-cli/src/launch/task-loader.mjs

@@ -0,0 +1,85 @@
+// task-loader.mjs — pure: load + validate a task definition from schedules/.
+// Task path: <repoRoot>/schedules/<id>.json
+// Required fields: id, command
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const REQUIRED_FIELDS = ['id', 'command'];
+
+/**
+ * Reject task commands that contain shell quoting. The runner spawns
+ * commands directly (no shell), so quotes are not honoured — they would
+ * silently shred the args (e.g. `bash -c "a && b"` → spawn('bash',
+ * ['-c', '"a', '&&', 'b"']), bash exits 2 with "unexpected EOF").
+ *
+ * Validated at load time so --dry-run also catches the bad shape, and
+ * re-asserted by runner.parseCommand as a chokepoint guarantee for
+ * programmatic callers.
+ *
+ * @param {string} command
+ * @throws {Error & { exitCode: 2 }} if command is not a non-empty string,
+ *   or contains a single (') or double (") quote character
+ */
+export function assertNoShellQuoting(command) {
+  if (typeof command !== 'string') {
+    const e = new Error('command must be a string');
+    e.exitCode = 2;
+    throw e;
+  }
+  const m = command.match(/['"]/);
+  if (m) {
+    const e = new Error(
+      `command contains shell quoting (${JSON.stringify(m[0])} at index ${m.index}) — ` +
+      'the runner spawns commands directly without a shell, so quotes are not honoured ' +
+      'and would silently shred the args. If you need shell features (variable expansion, ' +
+      '&&, pipes, sourcing), wrap the command in a script file and invoke the script, ' +
+      'or move the shell wrapper to the cron entry instead of the task command.'
+    );
+    e.exitCode = 2;
+    throw e;
+  }
+}
+
+export async function loadTask(repoRoot, taskId) {
+  const path = join(repoRoot, 'schedules', `${taskId}.json`);
+  let raw;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      const e = new Error(`task "${taskId}" not found in schedules (${path})`);
+      e.exitCode = 2;
+      throw e;
+    }
+    const e = new Error(`could not read schedule file for "${taskId}": ${err.message}`);
+    e.exitCode = 3;
+    throw e;
+  }
+
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (err) {
+    const e = new Error(`schedule file for "${taskId}" is not valid JSON: ${err.message}`);
+    e.exitCode = 2;
+    throw e;
+  }
+
+  for (const field of REQUIRED_FIELDS) {
+    if (!data[field]) {
+      const e = new Error(`task "${taskId}": missing required field "${field}"`);
+      e.exitCode = 2;
+      throw e;
+    }
+  }
+
+  try {
+    assertNoShellQuoting(data.command);
+  } catch (err) {
+    const e = new Error(`task "${taskId}": ${err.message}`);
+    e.exitCode = err.exitCode ?? 2;
+    throw e;
+  }
+
+  return data;
+}

package/dist/engineering-pa-cli/src/lint/cli.mjs

@@ -0,0 +1,61 @@
+// lint — voice/format linter subcommand router.
+//
+// Wired as `pa lint <verb>` (verb-second pattern, mirrors `pa gsc`). Today the
+// sole verb is `linkedin`; the router exists so other surfaces (article,
+// newsletter) can land as sibling verbs without reshaping the dispatch.
+//
+// Exit codes are lint-semantic and owned by each command (0 clean / 1 errors /
+// 2 warnings / 3 usage|IO|config) — see docs/lint-linkedin.md. The router
+// itself returns 3 for its own usage errors (no verb, unknown verb).
+
+import { run as runLinkedin } from './commands/linkedin.mjs';
+
+const HELP = `pa lint — lint operator-authored text against voice rules
+
+Usage:
+  pa lint linkedin <input-file> [--rules <path>] [--format <text|json>]
+                                [--severity <error|warning|info>] [--surface <name>]
+      Lint a file against the LinkedIn voice-rule corpus and report
+      violations in alter-format (swap → / cut → / rename →).
+
+  pa lint -h, --help
+      Show this help.
+
+Exit codes (lint-semantic, ESLint-style — see docs/lint-linkedin.md):
+  0 clean | 1 errors found | 2 warnings only | 3 usage / IO / config error
+`;
+
+export async function run(argv, overrides = {}) {
+  const verb = argv[0];
+  const rest = argv.slice(1);
+
+  if (!verb || verb === '--help' || verb === '-h' || verb === 'help') {
+    (overrides.stdout ?? process.stdout).write(HELP);
+    // No verb is a usage error (3); explicit help is success (0).
+    return verb ? 0 : 3;
+  }
+
+  switch (verb) {
+    case 'linkedin':
+      return runLinkedin(rest, overrides);
+    default:
+      (overrides.stderr ?? process.stderr).write(`[pa lint] unknown verb: ${verb}\n`);
+      (overrides.stdout ?? process.stdout).write(HELP);
+      return 3;
+  }
+}
+
+// CLI entry: map thrown errors to exit codes (err.exitCode or 3 for the
+// lint family — every non-finding failure here is usage/IO/config).
+export async function main(argv, overrides = {}) {
+  try {
+    const code = await run(argv, overrides);
+    return code ?? 0;
+  } catch (err) {
+    const code = err && typeof err.exitCode === 'number' ? err.exitCode : 3;
+    (overrides.stderr ?? process.stderr).write(
+      `pa lint: ${err && err.message ? err.message : err}\n`,
+    );
+    return code;
+  }
+}

package/dist/engineering-pa-cli/src/lint/commands/linkedin.mjs

@@ -0,0 +1,133 @@
+// linkedin.mjs — `pa lint linkedin <file>` command.
+//
+// Loads the voice-rule corpus, lints the input file, prints violations in
+// alter-format, and returns a lint-semantic exit code.
+//
+// Exit codes for this command (deliberately lint-semantic, ESLint-style —
+// see docs/lint-linkedin.md for why this differs from tooling standard §6):
+//   0 clean (or only info / below floor) | 1 errors found |
+//   2 warnings only | 3 usage / IO / config error
+
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getRepoRoot } from '../../pa/repo-root.mjs';
+import { loadRules } from '../rules.mjs';
+import { lint, applySeverityFloor, exitCodeFor } from '../linter.mjs';
+import { formatText, formatJson } from '../reporter.mjs';
+
+const DEFAULT_RULES_REL = 'operator/knowledge/writing/linkedin-rules.json';
+const FORMATS = new Set(['text', 'json']);
+const SEVERITIES = new Set(['error', 'warning', 'info']);
+
+export const USAGE = `pa lint linkedin — lint text against the LinkedIn voice rules
+
+Usage:
+  pa lint linkedin <input-file> [options]
+
+Options:
+  --rules <path>        Rule corpus JSON. Defaults to
+                        ${DEFAULT_RULES_REL} relative to the operator repo
+                        root; required if that file is absent.
+  --format <text|json>  Output format (default: text).
+  --severity <error|warning|info>
+                        Severity floor — only violations at or above this
+                        level are reported (default: error).
+  --surface <name>      Surface context: all | linkedin | article |
+                        newsletter | reply (default: linkedin). Rules whose
+                        surface is "all" or includes this value apply.
+  -h, --help            Show this help.
+
+Output (text): one line per violation —
+  <file>:<line>:<col>  <severity>  <ruleId>  <matched>  →  <alter-guidance>
+
+Exit codes (lint-semantic):
+  0 clean | 1 errors found | 2 warnings only | 3 usage / IO / config error
+`;
+
+function usageError(message) {
+  return Object.assign(new Error(message), { exitCode: 3 });
+}
+
+// Minimal flag parser: one positional (the input file) plus the long flags
+// above. Unknown flags and missing flag values are usage errors.
+export function parseArgs(argv) {
+  const opts = { file: null, rules: null, format: 'text', severity: 'error', surface: 'linkedin' };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const takeValue = (name) => {
+      const v = argv[i + 1];
+      if (v === undefined) throw usageError(`${name} requires a value`);
+      i += 1;
+      return v;
+    };
+    switch (arg) {
+      case '--rules': opts.rules = takeValue('--rules'); break;
+      case '--format': opts.format = takeValue('--format'); break;
+      case '--severity': opts.severity = takeValue('--severity'); break;
+      case '--surface': opts.surface = takeValue('--surface'); break;
+      default:
+        if (arg.startsWith('-')) throw usageError(`unknown flag: ${arg}`);
+        if (opts.file !== null) throw usageError(`unexpected extra argument: ${arg}`);
+        opts.file = arg;
+    }
+  }
+  if (!opts.file) throw usageError('missing <input-file>');
+  if (!FORMATS.has(opts.format)) throw usageError(`invalid --format "${opts.format}" (text|json)`);
+  if (!SEVERITIES.has(opts.severity)) {
+    throw usageError(`invalid --severity "${opts.severity}" (error|warning|info)`);
+  }
+  return opts;
+}
+
+// Resolve the rules path: explicit --rules wins; otherwise the default under
+// the operator repo root, if that file exists. No default and no flag is a
+// usage error with an actionable message.
+async function resolveRulesPath(explicit) {
+  if (explicit) {
+    if (!existsSync(explicit)) throw usageError(`rules file not found: ${explicit}`);
+    return explicit;
+  }
+  let root;
+  try {
+    root = await getRepoRoot();
+  } catch {
+    root = null;
+  }
+  if (root) {
+    const candidate = join(root, DEFAULT_RULES_REL);
+    if (existsSync(candidate)) return candidate;
+  }
+  throw usageError(
+    `no --rules given and default corpus not found (expected ${DEFAULT_RULES_REL} under the repo root); pass --rules <path>`,
+  );
+}
+
+export async function run(argv, overrides = {}) {
+  const out = overrides.stdout ?? process.stdout;
+  if (argv[0] === '-h' || argv[0] === '--help') {
+    out.write(USAGE);
+    return 0;
+  }
+  const opts = parseArgs(argv);
+
+  const rulesPath = await resolveRulesPath(opts.rules);
+  const rules = await loadRules(rulesPath);
+
+  let text;
+  try {
+    text = await readFile(opts.file, 'utf8');
+  } catch (e) {
+    throw usageError(`cannot read input file ${opts.file}: ${e.message}`);
+  }
+
+  const all = lint(text, rules, { surface: opts.surface });
+  const reported = applySeverityFloor(all, opts.severity);
+
+  if (opts.format === 'json') {
+    out.write(formatJson(reported, opts.file) + '\n');
+  } else if (reported.length > 0) {
+    out.write(formatText(reported, opts.file) + '\n');
+  }
+  return exitCodeFor(reported);
+}

package/dist/engineering-pa-cli/src/lint/detectors.mjs

@@ -0,0 +1,90 @@
+// detectors.mjs — the three detector types for the linkedin voice linter.
+//
+// A detector takes the input text and a rule's `detect` block and returns an
+// array of matches: { line, col, matched }. Lines and columns are 1-based so
+// the text reporter can emit clickable `file:line:col` pointers.
+//
+// `literal-phrase` and `regex` scan line-by-line so positions fall out
+// naturally and a regex's negated character classes (e.g. `[^.,;]`) cannot
+// silently swallow newlines. `count` is document-wide: it flags every match
+// beyond `max` so the writer sees each excess occurrence, not just the count.
+
+const WORD = /\w/;
+
+// Escape a literal string for safe embedding in a RegExp source.
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Build the RegExp used by a `literal-phrase` detector.
+//
+// Word boundaries are applied conditionally: a leading `\b` only when the
+// phrase starts with a word character, a trailing `\b` only when it ends with
+// one. A blanket `\b...\b` around a phrase like "it's worth noting" is fine,
+// but around punctuation-edged phrases it would never match — conditional
+// anchoring keeps boundaries meaningful without false negatives.
+function buildPhraseRegex(detect) {
+  const phrase = detect.phrase ?? '';
+  const wordBoundary = detect.wordBoundary !== false; // default true
+  const caseSensitive = detect.caseSensitive === true; // default false
+  let src = escapeRegex(phrase);
+  if (wordBoundary) {
+    if (WORD.test(phrase[0] ?? '')) src = '\\b' + src;
+    if (WORD.test(phrase[phrase.length - 1] ?? '')) src = src + '\\b';
+  }
+  return new RegExp(src, caseSensitive ? 'g' : 'gi');
+}
+
+function buildRegex(detect) {
+  const caseSensitive = detect.caseSensitive === true; // default false
+  return new RegExp(detect.pattern, caseSensitive ? 'g' : 'gi');
+}
+
+// Scan one line for every non-overlapping match of `re` (which must carry the
+// global flag). Returns [{ col, matched }] with 1-based columns.
+function scanLine(line, re) {
+  const out = [];
+  re.lastIndex = 0;
+  let m;
+  while ((m = re.exec(line)) !== null) {
+    out.push({ col: m.index + 1, matched: m[0] });
+    // Guard against zero-width matches looping forever.
+    if (m.index === re.lastIndex) re.lastIndex += 1;
+  }
+  return out;
+}
+
+// Walk the document line-by-line, applying `re` to each line.
+function scanDocument(text, re) {
+  const out = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    for (const hit of scanLine(lines[i], re)) {
+      out.push({ line: i + 1, col: hit.col, matched: hit.matched });
+    }
+  }
+  return out;
+}
+
+// Dispatch a rule's detect block against the text.
+export function detect(text, detectBlock) {
+  switch (detectBlock.type) {
+    case 'literal-phrase':
+      return scanDocument(text, buildPhraseRegex(detectBlock));
+    case 'regex':
+      return scanDocument(text, buildRegex(detectBlock));
+    case 'count': {
+      const re = buildRegex({ pattern: detectBlock.pattern, caseSensitive: detectBlock.caseSensitive });
+      const all = scanDocument(text, re);
+      const max = Number.isFinite(detectBlock.max) ? detectBlock.max : 0;
+      // Pass if matches <= max. Otherwise flag every occurrence past the
+      // ceiling (the (max+1)th onward) so each excess use is actionable.
+      return all.length > max ? all.slice(max) : [];
+    }
+    default:
+      // Unreachable when rules are validated upstream, but be defensive.
+      throw Object.assign(new Error(`unknown detect type: ${detectBlock.type}`), { exitCode: 3 });
+  }
+}
+
+export { escapeRegex, buildPhraseRegex, buildRegex, scanLine, scanDocument };

package/dist/engineering-pa-cli/src/lint/linter.mjs

@@ -0,0 +1,69 @@
+// linter.mjs — run a validated rule corpus over an input text.
+//
+// Pure engine: no IO, no process exit. Takes text + rules + options, returns
+// a flat list of violations sorted by position. The CLI layer handles file
+// reading, severity-floor filtering, formatting, and exit codes.
+
+import { detect } from './detectors.mjs';
+import { ruleAppliesToSurface } from './rules.mjs';
+
+const SEVERITY_RANK = { info: 0, warning: 1, error: 2 };
+
+// Render a rule's alter block into a single guidance string in alter-format:
+//   swap   -> "swap → "use" | "X""  (the candidate replacements, then why)
+//   cut    -> "cut → <guidance>"
+//   rename -> "rename → <guidance>"
+export function formatAlter(alter) {
+  if (alter.kind === 'swap') {
+    const opts = alter.with.map((w) => JSON.stringify(w)).join(' | ');
+    return `swap → ${opts} — ${alter.guidance}`;
+  }
+  if (alter.kind === 'cut') return `cut → ${alter.guidance}`;
+  return `rename → ${alter.guidance}`;
+}
+
+// Lint `text` against `rules` for the given surface. Returns every violation
+// (unfiltered by severity); ordering is by line then column then ruleId so
+// output is deterministic.
+export function lint(text, rules, { surface = 'linkedin' } = {}) {
+  const violations = [];
+  for (const rule of rules) {
+    if (!ruleAppliesToSurface(rule, surface)) continue;
+    for (const hit of detect(text, rule.detect)) {
+      violations.push({
+        line: hit.line,
+        col: hit.col,
+        ruleId: rule.ruleId,
+        category: rule.category,
+        severity: rule.severity,
+        matched: hit.matched,
+        alter: formatAlter(rule.alter),
+        alterKind: rule.alter.kind,
+        rationale: rule.rationale,
+        source: rule.source,
+      });
+    }
+  }
+  violations.sort((a, b) =>
+    a.line - b.line || a.col - b.col || a.ruleId.localeCompare(b.ruleId),
+  );
+  return violations;
+}
+
+// Keep only violations at or above the severity floor.
+export function applySeverityFloor(violations, floor) {
+  const min = SEVERITY_RANK[floor] ?? SEVERITY_RANK.error;
+  return violations.filter((v) => SEVERITY_RANK[v.severity] >= min);
+}
+
+// Exit code from the reported (post-floor) violations, per the lint contract:
+//   1 = at least one error   2 = warnings (no errors)   0 = info-only or clean
+export function exitCodeFor(violations) {
+  let worst = -1;
+  for (const v of violations) worst = Math.max(worst, SEVERITY_RANK[v.severity]);
+  if (worst === SEVERITY_RANK.error) return 1;
+  if (worst === SEVERITY_RANK.warning) return 2;
+  return 0;
+}
+
+export { SEVERITY_RANK };

package/dist/engineering-pa-cli/src/lint/reporter.mjs

@@ -0,0 +1,32 @@
+// reporter.mjs — render violations as text or JSON.
+//
+// text: one line per violation —
+//   <file>:<line>:<col>  <severity>  <ruleId>  <matched>  →  <alter-guidance>
+// json: a machine-readable array, each entry
+//   { file, line, col, ruleId, severity, matched, alter, rationale, source }
+
+export function formatText(violations, file) {
+  return violations
+    .map((v) =>
+      `${file}:${v.line}:${v.col}  ${v.severity}  ${v.ruleId}  ${JSON.stringify(v.matched)}  →  ${v.alter}`,
+    )
+    .join('\n');
+}
+
+export function toJsonShape(violations, file) {
+  return violations.map((v) => ({
+    file,
+    line: v.line,
+    col: v.col,
+    ruleId: v.ruleId,
+    severity: v.severity,
+    matched: v.matched,
+    alter: v.alter,
+    rationale: v.rationale,
+    source: v.source,
+  }));
+}
+
+export function formatJson(violations, file) {
+  return JSON.stringify(toJsonShape(violations, file), null, 2);
+}

package/dist/engineering-pa-cli/src/lint/rules.mjs

@@ -0,0 +1,132 @@
+// rules.mjs — load and validate the linkedin voice-rule corpus.
+//
+// The corpus is a JSON array of rule objects. The schema is the contract
+// shared with the production corpus authored at
+// operator/knowledge/writing/linkedin-rules.json. Validation is strict: a
+// malformed corpus is a configuration error (exit 3), not a lint finding —
+// we refuse to run rather than silently skip broken rules.
+
+import { readFile } from 'node:fs/promises';
+
+const CATEGORIES = new Set([
+  'punctuation', 'vocabulary', 'phrase', 'reaction-phrase',
+  'filler', 'structural', 'format', 'count',
+]);
+const SEVERITIES = new Set(['error', 'warning', 'info']);
+const SURFACES = new Set(['all', 'linkedin', 'article', 'newsletter', 'reply']);
+const DETECT_TYPES = new Set(['literal-phrase', 'regex', 'count']);
+const ALTER_KINDS = new Set(['swap', 'cut', 'rename']);
+
+function configError(message) {
+  return Object.assign(new Error(message), { exitCode: 3 });
+}
+
+// Validate one rule, throwing a configError describing the first problem.
+// `where` locates the rule in the corpus for the operator.
+function validateRule(rule, where) {
+  if (rule === null || typeof rule !== 'object' || Array.isArray(rule)) {
+    throw configError(`${where}: rule must be an object`);
+  }
+  const id = typeof rule.ruleId === 'string' ? rule.ruleId : null;
+  if (!id) throw configError(`${where}: missing or non-string ruleId`);
+  const at = `rule "${id}"`;
+
+  if (!CATEGORIES.has(rule.category)) {
+    throw configError(`${at}: invalid category "${rule.category}"`);
+  }
+  if (!Array.isArray(rule.surface) || rule.surface.length === 0) {
+    throw configError(`${at}: surface must be a non-empty array`);
+  }
+  for (const s of rule.surface) {
+    if (!SURFACES.has(s)) throw configError(`${at}: invalid surface "${s}"`);
+  }
+  if (!SEVERITIES.has(rule.severity)) {
+    throw configError(`${at}: invalid severity "${rule.severity}"`);
+  }
+
+  const d = rule.detect;
+  if (!d || typeof d !== 'object') throw configError(`${at}: missing detect block`);
+  if (!DETECT_TYPES.has(d.type)) throw configError(`${at}: invalid detect.type "${d.type}"`);
+  if (d.type === 'literal-phrase') {
+    if (typeof d.phrase !== 'string' || d.phrase.length === 0) {
+      throw configError(`${at}: literal-phrase detect needs a non-empty phrase`);
+    }
+  } else if (d.type === 'regex') {
+    if (typeof d.pattern !== 'string' || d.pattern.length === 0) {
+      throw configError(`${at}: regex detect needs a pattern`);
+    }
+    assertCompiles(d.pattern, at);
+  } else if (d.type === 'count') {
+    if (typeof d.pattern !== 'string' || d.pattern.length === 0) {
+      throw configError(`${at}: count detect needs a pattern`);
+    }
+    if (typeof d.max !== 'number' || !Number.isFinite(d.max) || d.max < 0) {
+      throw configError(`${at}: count detect needs a non-negative numeric max`);
+    }
+    assertCompiles(d.pattern, at);
+  }
+
+  const a = rule.alter;
+  if (!a || typeof a !== 'object') throw configError(`${at}: missing alter block`);
+  if (!ALTER_KINDS.has(a.kind)) throw configError(`${at}: invalid alter.kind "${a.kind}"`);
+  if (typeof a.guidance !== 'string' || a.guidance.length === 0) {
+    throw configError(`${at}: alter needs guidance`);
+  }
+  if (a.kind === 'swap') {
+    if (!Array.isArray(a.with) || a.with.length === 0 || !a.with.every((w) => typeof w === 'string')) {
+      throw configError(`${at}: swap alter needs a non-empty array of string replacements`);
+    }
+  }
+
+  if (typeof rule.rationale !== 'string' || rule.rationale.length === 0) {
+    throw configError(`${at}: missing rationale`);
+  }
+  if (typeof rule.source !== 'string' || rule.source.length === 0) {
+    throw configError(`${at}: missing source`);
+  }
+  return id;
+}
+
+function assertCompiles(pattern, at) {
+  try {
+    new RegExp(pattern);
+  } catch (e) {
+    throw configError(`${at}: detect pattern does not compile: ${e.message}`);
+  }
+}
+
+// Validate a parsed corpus (array of rules). Returns the rules unchanged.
+export function validateCorpus(rules) {
+  if (!Array.isArray(rules)) throw configError('rule corpus must be a JSON array');
+  const seen = new Set();
+  rules.forEach((rule, i) => {
+    const id = validateRule(rule, `corpus[${i}]`);
+    if (seen.has(id)) throw configError(`duplicate ruleId "${id}"`);
+    seen.add(id);
+  });
+  return rules;
+}
+
+// Read, parse, and validate the corpus at `path`.
+export async function loadRules(path) {
+  let raw;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (e) {
+    throw configError(`cannot read rules file ${path}: ${e.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    throw configError(`rules file ${path} is not valid JSON: ${e.message}`);
+  }
+  return validateCorpus(parsed);
+}
+
+// Rule applies if it targets the active surface ("all" matches every surface).
+export function ruleAppliesToSurface(rule, surface) {
+  return rule.surface.includes('all') || rule.surface.includes(surface);
+}
+
+export { CATEGORIES, SEVERITIES, SURFACES, DETECT_TYPES, ALTER_KINDS };