@ai-is-gonna/get-tasks-done 0.2.0

package/scripts/lint-command-contract.cjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * lint-command-contract.cjs  (ADR-0002)
+ *
+ * Enforces the commands/gtd/*.md contract across all 65 command files:
+ *
+ *   1. name:        present, non-empty, matches gtd: or gtd- prefix
+ *   2. description: present, non-empty
+ *   3. allowed-tools: block present, non-empty, all entries from CANONICAL_TOOLS
+ *   4. execution_context @-refs: every @-reference resolves to an existing file on disk
+ *   5. execution_context @-refs: each appears on its own line (no trailing prose)
+ *
+ * Exit 0 = clean. Exit 1 = violations (with diagnostics).
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const ROOT          = path.join(__dirname, '..');
+const COMMANDS_DIR  = path.join(ROOT, 'commands', 'gtd');
+const GTD_ROOT      = path.join(ROOT, 'get-tasks-done');
+
+const {
+  CANONICAL_TOOLS,
+  parseFrontmatter,
+  executionContextRefs: extractExecutionContextRefs,
+} = require('./command-contract-helpers.cjs');
+
+// ─── check one file ───────────────────────────────────────────────────────────
+
+function check(filePath) {
+  const content  = fs.readFileSync(filePath, 'utf-8');
+  const rel      = path.relative(ROOT, filePath);
+  const fm       = parseFrontmatter(content);
+  const violations = [];
+
+  // 1. name: present + gtd: / gtd- prefix
+  if (!fm.name || !fm.name.trim()) {
+    violations.push('name: field missing or empty');
+  } else if (!/^gtd[:-]/.test(fm.name.trim())) {
+    violations.push(`name: must start with "gtd:" or "gtd-", got "${fm.name.trim()}"`);
+  }
+
+  // 2. description: present + non-empty
+  if (!fm.description || !fm.description.trim()) {
+    violations.push('description: field missing or empty');
+  }
+
+  // 3. allowed-tools: present + non-empty + all entries canonical
+  if (!fm['allowed-tools'] || !fm['allowed-tools'].trim()) {
+    violations.push('allowed-tools: block missing or empty');
+  } else {
+    const tools = fm['allowed-tools'].split('\n').map(t => t.trim()).filter(Boolean);
+    for (const tool of tools) {
+      const valid =
+        CANONICAL_TOOLS.has(tool) ||
+        (tool.startsWith('mcp__context7__') && CANONICAL_TOOLS.has('mcp__context7__*'));
+      if (!valid) violations.push(`allowed-tools: unknown tool "${tool}"`);
+    }
+  }
+
+  // 4+5. execution_context @-refs resolve + no trailing prose
+  const refs = extractExecutionContextRefs(content);
+  for (const { token, normalized, trailingProse } of refs) {
+    const absPath = path.join(GTD_ROOT, normalized);
+    if (!fs.existsSync(absPath)) {
+      violations.push(`execution_context: @-ref "${normalized}" does not exist on disk`);
+    }
+    if (trailingProse) {
+      violations.push(`execution_context: @-ref "${token}" has trailing prose on the same line`);
+    }
+  }
+
+  if (violations.length === 0) return null;
+  return { file: rel, violations };
+}
+
+// ─── run ─────────────────────────────────────────────────────────────────────
+
+const commandFiles = fs
+  .readdirSync(COMMANDS_DIR)
+  .filter(f => f.endsWith('.md'))
+  .map(f => path.join(COMMANDS_DIR, f));
+
+const results = commandFiles.map(check).filter(Boolean);
+
+if (results.length === 0) {
+  console.log(
+    `ok lint-command-contract: ${commandFiles.length} command files checked, 0 violations`,
+  );
+  process.exit(0);
+}
+
+const total = results.reduce((n, r) => n + r.violations.length, 0);
+process.stderr.write(
+  `\nERROR lint-command-contract: ${total} violation(s) across ${results.length} file(s)\n\n`,
+);
+for (const r of results) {
+  process.stderr.write(`  ${r.file}\n`);
+  for (const v of r.violations) {
+    process.stderr.write(`    - ${v}\n`);
+  }
+  process.stderr.write('\n');
+}
+process.stderr.write('See scripts/command-contract-helpers.cjs for the command contract spec.\n\n');
+process.exit(1);

package/scripts/lint-descriptions.cjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * lint-descriptions.cjs
+ *
+ * Enforces the 100-char description budget for commands/gtd/*.md files.
+ *
+ * Usage:
+ *   node scripts/lint-descriptions.cjs [file.md ...]
+ *
+ * If no args are given, scans commands/gtd/ automatically.
+ * Exits 1 if any description exceeds 100 chars; exits 0 if all pass.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const MAX_LENGTH = 100;
+const COMMANDS_DIR = path.join(__dirname, '..', 'commands', 'gtd');
+
+/**
+ * Parse the description field from frontmatter in a .md file.
+ * Returns null if no description is found.
+ */
+function parseDescription(content) {
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) return null;
+  const fm = fmMatch[1];
+
+  const quoted = fm.match(/^description:\s+"((?:[^"\\]|\\.)*)"\s*$/m);
+  if (quoted) return quoted[1];
+
+  const plain = fm.match(/^description:\s+(.+)$/m);
+  if (plain) return plain[1].trim();
+
+  return null;
+}
+
+function getFiles() {
+  if (process.argv.length > 2) {
+    return process.argv.slice(2);
+  }
+  return fs.readdirSync(COMMANDS_DIR)
+    .filter(f => f.endsWith('.md'))
+    .map(f => path.join(COMMANDS_DIR, f));
+}
+
+const files = getFiles();
+const violations = [];
+
+for (const filePath of files) {
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf-8');
+  } catch (err) {
+    process.stderr.write(`ERROR: Cannot read file: ${filePath}\n  ${err.message}\n`);
+    process.exit(1);
+  }
+
+  const description = parseDescription(content);
+  if (description === null) continue;
+
+  if (description.length > MAX_LENGTH) {
+    violations.push({ filePath, length: description.length, description });
+  }
+}
+
+if (violations.length === 0) {
+  const checked = files.length;
+  process.stdout.write(`ok lint-descriptions: ${checked} file(s) checked, 0 violations\n`);
+  process.exit(0);
+}
+
+process.stderr.write(`\nERROR lint-descriptions: ${violations.length} violation(s) found\n\n`);
+for (const v of violations) {
+  const preview = v.description.length > 120 ? v.description.slice(0, 117) + '...' : v.description;
+  process.stderr.write(`  ${v.filePath}\n`);
+  process.stderr.write(`    Length : ${v.length} (max ${MAX_LENGTH})\n`);
+  process.stderr.write(`    Desc   : ${preview}\n\n`);
+}
+process.stderr.write(`Trim descriptions to <= ${MAX_LENGTH} chars. Flag docs belong in argument-hint:.\n\n`);
+process.exit(1);

package/scripts/lint-no-source-grep-extras.cjs

@@ -0,0 +1,81 @@
+'use strict';
+
+/**
+ * Extended detector for the no-source-grep rule (#2982).
+ *
+ * The base lint (scripts/lint-no-source-grep.cjs) only catches the
+ * direct-chain form: readFileSync(...).includes(...). The much more common
+ * var-binding form escapes it:
+ *
+ *   const src = fs.readFileSync(p, 'utf8');
+ *   // ... 50 lines later ...
+ *   assert.ok(src.includes('foo'));   // ← still source-grep, lint missed it
+ *
+ * This module exposes pure detectors that scan source text and return
+ * structured violation records. The CLI wrapper (in the base lint) calls
+ * these for each test file.
+ *
+ * Tests assert on the typed VIOLATION enum codes, not on prose messages.
+ */
+
+const VIOLATION = Object.freeze({
+  VAR_FROM_READFILE_USED_IN_TEXT_MATCH: 'var_from_readfile_used_in_text_match',
+  WRAPPED_ASSERT_OK_MATCH: 'wrapped_assert_ok_match',
+});
+
+const TEXT_MATCH_METHODS = ['includes', 'startsWith', 'endsWith', 'match', 'search'];
+
+/**
+ * Single-pass scanner. Tracks variables bound from a readFileSync call,
+ * then flags any subsequent <var>.<method>( use where method is one of
+ * TEXT_MATCH_METHODS.
+ */
+function detectVarBindingViolations(src) {
+  // Pass 1: collect variables bound from readFileSync.
+  // Matches:   const|let|var <name> = [fs.]readFileSync(
+  const bindRe = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:[A-Za-z_$][\w$.]*\.)?readFileSync\s*\(/g;
+  const boundVars = new Set();
+  let m;
+  while ((m = bindRe.exec(src)) !== null) {
+    boundVars.add(m[1]);
+  }
+  if (boundVars.size === 0) return [];
+
+  // Pass 2: find <var>.<method>( on any bound var.
+  const findings = [];
+  // Build a regex alternation from the bound var names.
+  const alt = [...boundVars].map((v) => v.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
+  const useRe = new RegExp(
+    `\\b(${alt})\\s*\\.\\s*(${TEXT_MATCH_METHODS.join('|')})\\s*\\(`,
+    'g',
+  );
+  while ((m = useRe.exec(src)) !== null) {
+    findings.push({
+      kind: VIOLATION.VAR_FROM_READFILE_USED_IN_TEXT_MATCH,
+      variable: m[1],
+      method: m[2],
+    });
+  }
+  return findings;
+}
+
+/**
+ * Detects assert.ok(<expr>.match(/.../)) and assert.ok(<expr>.match(<expr>))
+ * which is the same anti-pattern as assert.match but escapes the simpler
+ * regex used by the base lint.
+ */
+function detectWrappedAssertOkMatch(src) {
+  const re = /assert\.ok\s*\(\s*[A-Za-z_$][\w$.]*\.match\s*\(/g;
+  const findings = [];
+  let m;
+  while ((m = re.exec(src)) !== null) {
+    findings.push({ kind: VIOLATION.WRAPPED_ASSERT_OK_MATCH });
+  }
+  return findings;
+}
+
+function detectAll(src) {
+  return [...detectVarBindingViolations(src), ...detectWrappedAssertOkMatch(src)];
+}
+
+module.exports = { detectVarBindingViolations, detectWrappedAssertOkMatch, detectAll, VIOLATION };

package/scripts/lint-no-source-grep.cjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * lint-no-source-grep.cjs
+ *
+ * Enforces the "no source-grep tests" rule:
+ *   Tests must NOT read source-code .cjs files with readFileSync to assert string
+ *   presence. That pattern (source-grep theater) proves a literal exists in source,
+ *   not that the runtime behavior is correct.
+ *
+ * ALLOWED:
+ *   - require('../get-tasks-done/bin/lib/foo.cjs')  -- runs the module, not text inspection
+ *   - readFileSync on .md / .json / .txt files     -- product-content or config output
+ *   - Files annotated: // allow-test-rule: <reason>
+ *
+ * DISALLOWED (without allow-test-rule):
+ *   - readFileSync where the path argument ends in a .cjs filename literal
+ *   - A path constant (e.g. CONFIG_PATH) assigned to a .cjs lib file, used in readFileSync
+ *
+ * Exit 0 = clean. Exit 1 = violations found (with diagnostics).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const TESTS_DIR = path.join(__dirname, '..', 'tests');
+const ALLOW_ANNOTATION = /\/\/\s*allow-test-rule:\s*\S/;
+
+// Matches constant definitions that hold a .cjs path in a SOURCE directory.
+// Requires a source-dir indicator ('bin', 'lib', 'get-tasks-done') to avoid
+// flagging temp files like path.join(tmpDir, 'example.cjs').
+//   const CONFIG_PATH = path.join(__dirname, '..', 'get-tasks-done', 'bin', 'lib', 'config-schema.cjs');
+const CJS_PATH_CONST_RE = /(?:const|let|var)\s+(\w+)\s*=\s*path\.join\s*\([^)]*(?:'bin'|"bin"|'lib'|"lib"|'get-tasks-done'|"get-tasks-done")[^)]*['"][^'"]*\.cjs['"]/gm;
+
+// Matches readFileSync with a named variable as first arg
+const READ_WITH_CONST_RE = /readFileSync\s*\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*,/gm;
+
+// Matches readFileSync with an inline path.join(.cjs) as first arg
+const READ_WITH_INLINE_CJS_RE = /readFileSync\s*\([^,)]*path\.join\s*\([^)]*(?:'bin'|"bin"|'lib'|"lib"|'get-tasks-done'|"get-tasks-done")[^)]*['"][^'"]*\.cjs['"]/;
+
+/**
+ * #2962-class violations: raw text matching against process output or file
+ * content. The rule from CONTRIBUTING.md "Prohibited: Raw Text Matching on
+ * Test Outputs": tests assert on typed structured fields, never on rendered
+ * text. Patterns below are the obvious anti-patterns; subtler hidden forms
+ * (e.g. wrapping the same logic in a parser function) are still forbidden
+ * by the prose rule but cannot be detected lexically without an AST.
+ */
+const RAW_MATCH_PATTERNS = [
+  {
+    re: /assert\.(?:match|doesNotMatch)\s*\(\s*[A-Za-z_$][A-Za-z0-9_$]*\.(?:stdout|stderr)\b/,
+    label: 'assert.match/doesNotMatch on .stdout/.stderr (emit --json from the SUT and assert on typed fields)',
+  },
+  {
+    re: /\.(?:stdout|stderr)\.(?:includes|startsWith|endsWith)\s*\(/,
+    label: '.stdout/.stderr substring match (emit --json and assert on typed fields)',
+  },
+  {
+    re: /readFileSync\s*\([^)]*\)\s*\.(?:includes|startsWith|endsWith)\s*\(/,
+    label: 'readFileSync(...).<includes|startsWith|endsWith> (expose an IR from production code; assert on its fields)',
+  },
+];
+
+function setFromMatches(content, re) {
+  const found = new Set();
+  let m;
+  const cloned = new RegExp(re.source, re.flags);
+  while ((m = cloned.exec(content)) !== null) found.add(m[1]);
+  return found;
+}
+
+function check(filepath) {
+  const content = fs.readFileSync(filepath, 'utf-8');
+  const rel = path.relative(path.join(__dirname, '..'), filepath);
+
+  if (ALLOW_ANNOTATION.test(content)) return null;
+
+  const violations = [];
+
+  // Pattern A: readFileSync(path.join(..., 'foo.cjs'), ...)
+  if (READ_WITH_INLINE_CJS_RE.test(content)) {
+    violations.push({
+      reason: 'readFileSync with inline .cjs path literal',
+      fix: 'Replace with runGtdTools() behavioral test, or add // allow-test-rule: <reason>',
+    });
+  }
+
+  // Pattern B: const FOO_PATH = path.join(..., 'foo.cjs')  +  readFileSync(FOO_PATH, ...)
+  const cjsConsts = setFromMatches(content, CJS_PATH_CONST_RE);
+  if (cjsConsts.size > 0) {
+    const readConsts = setFromMatches(content, READ_WITH_CONST_RE);
+    const overlap = [...cjsConsts].filter(c => readConsts.has(c));
+    if (overlap.length > 0) {
+      violations.push({
+        reason: `source .cjs path constant(s) used in readFileSync: ${overlap.join(', ')}`,
+        fix: 'Replace with runGtdTools() behavioral test, or add // allow-test-rule: <reason>',
+      });
+    }
+  }
+
+  // Patterns C..E: raw text matching against process output or file content.
+  // See CONTRIBUTING.md "Prohibited: Raw Text Matching on Test Outputs".
+  for (const { re, label } of RAW_MATCH_PATTERNS) {
+    if (re.test(content)) {
+      violations.push({
+        reason: label,
+        fix: 'Expose typed IR from production code; assert on structured fields. Or add // allow-test-rule: <reason>',
+      });
+    }
+  }
+
+  // Patterns F..G (#2982): var-binding readFileSync().<text-method>() and
+  // assert.ok(<expr>.match(...)). These escape the simpler patterns above
+  // because the bind and the use are on different lines or wrapped.
+  const extras = require('./lint-no-source-grep-extras.cjs');
+  const varBindFindings = extras.detectVarBindingViolations(content);
+  if (varBindFindings.length > 0) {
+    const samples = varBindFindings.slice(0, 3)
+      .map((f) => `${f.variable}.${f.method}()`)
+      .join(', ');
+    violations.push({
+      reason: `readFileSync-bound variable used in text-match method: ${samples}${varBindFindings.length > 3 ? `, …+${varBindFindings.length - 3} more` : ''}`,
+      fix: 'Expose typed IR; assert on structured fields. Or // allow-test-rule: <reason>',
+    });
+  }
+  const wrappedFindings = extras.detectWrappedAssertOkMatch(content);
+  if (wrappedFindings.length > 0) {
+    violations.push({
+      reason: `assert.ok(<expr>.match(...)) — escapes assert.match rule (${wrappedFindings.length} occurrence${wrappedFindings.length > 1 ? 's' : ''})`,
+      fix: 'Use assert.equal on a typed field, not regex match on text. Or // allow-test-rule: <reason>',
+    });
+  }
+
+  if (violations.length === 0) return null;
+  return { file: rel, violations };
+}
+
+function findTestFiles(dir) {
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...findTestFiles(full));
+    } else if (entry.name.endsWith('.test.cjs')) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+const testFiles = findTestFiles(TESTS_DIR);
+
+const violations = testFiles.map(check).filter(Boolean);
+
+if (violations.length === 0) {
+  console.log(`ok lint-no-source-grep: ${testFiles.length} test files checked, 0 violations`);
+  process.exit(0);
+}
+
+const totalIssues = violations.reduce((n, v) => n + v.violations.length, 0);
+process.stderr.write(`\nERROR lint-no-source-grep: ${totalIssues} violation(s) across ${violations.length} file(s)\n\n`);
+for (const f of violations) {
+  process.stderr.write(`  ${f.file}\n`);
+  for (const v of f.violations) {
+    process.stderr.write(`    Problem : ${v.reason}\n`);
+    process.stderr.write(`    Fix     : ${v.fix}\n`);
+  }
+  process.stderr.write('\n');
+}
+process.stderr.write('See CONTRIBUTING.md "Prohibited: Source-Grep Tests" and\n');
+process.stderr.write('"Prohibited: Raw Text Matching on Test Outputs" for guidance.\n');
+process.stderr.write('Structural tests that legitimately read source files: add // allow-test-rule: <reason>\n\n');
+process.exit(1);

package/scripts/lint-pr-check-project-dir.cjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+
+const DEFAULT_RELATIVE_FILES = [
+  '.github/workflows/test.yml',
+  'scripts/lint-no-source-grep.cjs',
+  'scripts/lint-command-contract.cjs',
+  'scripts/lint-skill-deps.cjs',
+  'scripts/lint-descriptions.cjs',
+  'scripts/lint-shell-command-projection-drift.cjs',
+];
+
+function defaultFiles(rootDir = ROOT) {
+  return DEFAULT_RELATIVE_FILES
+    .map((file) => path.join(rootDir, file))
+    .filter((file) => fs.existsSync(file));
+}
+
+function findForbiddenCwd(content, file = '<inline>') {
+  const findings = [];
+  const lines = content.split(/\r?\n/);
+
+  lines.forEach((line, index) => {
+    const pattern = /\bcwd\b/g;
+    let match;
+    while ((match = pattern.exec(line)) !== null) {
+      findings.push({
+        file,
+        line: index + 1,
+        column: match.index + 1,
+        source: line.trim(),
+      });
+    }
+  });
+
+  return findings;
+}
+
+function checkFiles(files, { rootDir = ROOT } = {}) {
+  const findings = [];
+  for (const file of files) {
+    const content = fs.readFileSync(file, 'utf8');
+    const rel = path.relative(rootDir, file);
+    findings.push(...findForbiddenCwd(content, rel));
+  }
+  return findings;
+}
+
+function formatFindings(findings) {
+  const lines = [
+    `ERROR lint-pr-check-project-dir: ${findings.length} forbidden cwd reference(s) found`,
+    '',
+    'PR checkers must use projectDir for project roots; cwd is forbidden in this layer.',
+    '',
+  ];
+
+  for (const finding of findings) {
+    lines.push(`  ${finding.file}:${finding.line}:${finding.column}`);
+    lines.push(`    ${finding.source}`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function main(argv = process.argv.slice(2)) {
+  const files = argv.length > 0 ? argv.map((file) => path.resolve(file)) : defaultFiles();
+  const findings = checkFiles(files);
+
+  if (findings.length === 0) {
+    console.log(`ok lint-pr-check-project-dir: ${files.length} PR check files checked`);
+    return 0;
+  }
+
+  process.stderr.write(formatFindings(findings));
+  return 1;
+}
+
+if (require.main === module) {
+  process.exit(main());
+}
+
+module.exports = {
+  DEFAULT_RELATIVE_FILES,
+  checkFiles,
+  defaultFiles,
+  findForbiddenCwd,
+  formatFindings,
+  main,
+};

package/scripts/lint-shell-command-projection-drift.cjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Focused drift guard for issue #3442:
+ * prevent installer-owned inline shim/wrapper text builders from bypassing the
+ * Shell Command Projection Module seam.
+ *
+ * Scope intentionally excludes subprocess execution helpers (spawnSync /
+ * execFileSync) because those are safe internal execution primitives, not
+ * serialized shell-command rendering.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+const targetArg = process.argv[2] || path.join(ROOT, 'bin', 'install.js');
+const target = path.resolve(targetArg);
+const rel = path.relative(ROOT, target);
+
+let content;
+try {
+  content = fs.readFileSync(target, 'utf8');
+} catch (error) {
+  process.stderr.write(`lint-shell-command-projection-drift: failed to read ${target}: ${error.message}\n`);
+  process.exit(1);
+}
+
+const forbidden = [
+  {
+    label: 'inline cmd shim builder',
+    pattern: /@ECHO OFF\\r\\n@SETLOCAL\\r\\n@node /,
+  },
+  {
+    label: 'inline pwsh shim builder',
+    pattern: /#!\/usr\/bin\/env pwsh\\n& node /,
+  },
+  {
+    label: 'inline sh shim builder',
+    pattern: /#!\/usr\/bin\/env sh\\nexec node /,
+  },
+];
+
+const matches = forbidden.filter((rule) => rule.pattern.test(content));
+if (matches.length === 0) {
+  process.stdout.write(`ok shell-projection-drift: ${rel}\n`);
+  process.exit(0);
+}
+
+process.stderr.write(`ERROR shell-projection-drift: inline serialized shim builders found in ${rel}\n`);
+for (const match of matches) {
+  process.stderr.write(`  - ${match.label}\n`);
+}
+process.stderr.write('Route shim/wrapper rendering through get-tasks-done/bin/lib/shell-command-projection.cjs\n');
+process.stderr.write('Safe subprocess execution via spawnSync/execFileSync is intentionally allowed.\n');
+process.exit(1);