@karthikrajkumar.kannan/get-things-done 1.0.0

package/lib/file-ops.cjs

@@ -0,0 +1,106 @@
+/**
+ * GTD File Operations — Atomic writes, directory utilities, project root detection.
+ * @module lib/file-ops
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Write content to a file atomically.
+ * Writes to a temp file first, then renames (atomic on same filesystem).
+ * Prevents corruption if the process crashes mid-write.
+ *
+ * @param {string} targetPath - Absolute path to write to
+ * @param {string} content - File content
+ */
+function atomicWrite(targetPath, content) {
+  const tmpPath = targetPath + '.tmp.' + process.pid;
+  try {
+    const dir = path.dirname(targetPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(tmpPath, content, 'utf8');
+    fs.renameSync(tmpPath, targetPath);
+  } catch (err) {
+    try {
+      fs.unlinkSync(tmpPath);
+    } catch (_) {
+      // Ignore cleanup errors
+    }
+    throw err;
+  }
+}
+
+/**
+ * Ensure a directory exists (recursive mkdir).
+ * @param {string} dirPath - Directory path to create
+ */
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+/**
+ * Find the project root by walking up the directory tree.
+ * Looks for: .planning/, .git/, package.json
+ *
+ * @param {string} [startDir=process.cwd()] - Starting directory
+ * @returns {string|null} Project root path or null
+ */
+function findProjectRoot(startDir) {
+  let dir = startDir || process.cwd();
+  const root = path.parse(dir).root;
+
+  while (dir !== root) {
+    if (
+      fs.existsSync(path.join(dir, '.planning')) ||
+      fs.existsSync(path.join(dir, '.git')) ||
+      fs.existsSync(path.join(dir, 'package.json'))
+    ) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+
+  return null;
+}
+
+/**
+ * Check if a file exists.
+ * @param {string} filePath - Path to check
+ * @returns {boolean}
+ */
+function fileExists(filePath) {
+  try {
+    return fs.statSync(filePath).isFile();
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Read a file, returning a default value if it doesn't exist.
+ * @param {string} filePath - Path to read
+ * @param {string} defaultValue - Default if file missing
+ * @returns {string}
+ */
+function readFileOr(filePath, defaultValue) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch (_) {
+    return defaultValue;
+  }
+}
+
+module.exports = {
+  atomicWrite,
+  ensureDir,
+  findProjectRoot,
+  fileExists,
+  readFileOr,
+};

package/lib/frontmatter.cjs

@@ -0,0 +1,100 @@
+/**
+ * GTD Frontmatter Parser — YAML frontmatter between --- delimiters.
+ * @module lib/frontmatter
+ */
+
+'use strict';
+
+const FRONTMATTER_REGEX = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
+
+/**
+ * Parse YAML frontmatter from a Markdown string.
+ * Supports simple key: value pairs and basic types (string, number, boolean, null).
+ *
+ * @param {string} content - Markdown content with optional frontmatter
+ * @returns {{ frontmatter: object, body: string }}
+ */
+function parseFrontmatter(content) {
+  if (!content || typeof content !== 'string') {
+    return { frontmatter: {}, body: content || '' };
+  }
+
+  const match = content.match(FRONTMATTER_REGEX);
+  if (!match) {
+    return { frontmatter: {}, body: content };
+  }
+
+  const yamlBlock = match[1];
+  const body = match[2];
+  const frontmatter = parseSimpleYaml(yamlBlock);
+
+  return { frontmatter, body };
+}
+
+/**
+ * Serialize frontmatter and body back to a Markdown string.
+ *
+ * @param {object} frontmatter - Key-value pairs
+ * @param {string} body - Markdown body
+ * @returns {string}
+ */
+function serializeFrontmatter(frontmatter, body) {
+  if (!frontmatter || Object.keys(frontmatter).length === 0) {
+    return body || '';
+  }
+
+  const yamlLines = Object.entries(frontmatter).map(([key, value]) => {
+    if (value === null || value === undefined) return `${key}: null`;
+    if (typeof value === 'boolean') return `${key}: ${value}`;
+    if (typeof value === 'number') return `${key}: ${value}`;
+    if (typeof value === 'string' && value.includes(':')) return `${key}: "${value}"`;
+    return `${key}: ${value}`;
+  });
+
+  return `---\n${yamlLines.join('\n')}\n---\n${body || ''}`;
+}
+
+/**
+ * Parse simple YAML (flat key-value pairs only).
+ * Handles: strings, numbers, booleans, null, quoted strings.
+ *
+ * @param {string} yaml - YAML block content
+ * @returns {object}
+ */
+function parseSimpleYaml(yaml) {
+  const result = {};
+  const lines = yaml.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const colonIndex = trimmed.indexOf(':');
+    if (colonIndex === -1) continue;
+
+    const key = trimmed.slice(0, colonIndex).trim();
+    let value = trimmed.slice(colonIndex + 1).trim();
+
+    // Remove quotes
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    } else if (value === 'true') {
+      value = true;
+    } else if (value === 'false') {
+      value = false;
+    } else if (value === 'null' || value === '~' || value === '') {
+      value = null;
+    } else if (!isNaN(Number(value)) && value !== '') {
+      value = Number(value);
+    }
+
+    result[key] = value;
+  }
+
+  return result;
+}
+
+module.exports = {
+  parseFrontmatter,
+  serializeFrontmatter,
+};

package/lib/git.cjs

@@ -0,0 +1,137 @@
+/**
+ * GTD Git Integration — Git operations for state tracking and change detection.
+ * @module lib/git
+ */
+
+'use strict';
+
+const { execSync } = require('child_process');
+const path = require('path');
+
+/**
+ * Execute a git command and return stdout trimmed.
+ * Returns null on any error (not a git repo, git not installed, etc.)
+ *
+ * @param {string} command - Git command (without 'git' prefix)
+ * @param {string} cwd - Working directory
+ * @returns {string|null}
+ */
+function git(command, cwd) {
+  try {
+    return execSync(`git ${command}`, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 10000,
+    }).trim();
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Get the current short commit hash.
+ * @param {string} projectRoot - Project root directory
+ * @returns {string|null} 7-character commit hash or null
+ */
+function getGitCommit(projectRoot) {
+  return git('rev-parse --short HEAD', projectRoot);
+}
+
+/**
+ * Get the full commit hash.
+ * @param {string} projectRoot - Project root directory
+ * @returns {string|null} Full commit hash or null
+ */
+function getGitCommitFull(projectRoot) {
+  return git('rev-parse HEAD', projectRoot);
+}
+
+/**
+ * Get the current branch name.
+ * @param {string} projectRoot - Project root directory
+ * @returns {string|null} Branch name or null
+ */
+function getGitBranch(projectRoot) {
+  return git('rev-parse --abbrev-ref HEAD', projectRoot);
+}
+
+/**
+ * Check if there are uncommitted changes (staged or unstaged).
+ * @param {string} projectRoot - Project root directory
+ * @returns {boolean}
+ */
+function hasUncommittedChanges(projectRoot) {
+  const status = git('status --porcelain', projectRoot);
+  return status !== null && status.length > 0;
+}
+
+/**
+ * Get the list of files changed between two commits.
+ * @param {string} projectRoot - Project root directory
+ * @param {string} fromCommit - Starting commit hash
+ * @param {string} [toCommit='HEAD'] - Ending commit hash
+ * @returns {string[]} Array of changed file paths (relative to project root)
+ */
+function getChangedFiles(projectRoot, fromCommit, toCommit = 'HEAD') {
+  const output = git(`diff --name-only ${fromCommit}..${toCommit}`, projectRoot);
+  if (!output) return [];
+  return output.split('\n').filter((line) => line.length > 0);
+}
+
+/**
+ * Get recent commit messages for context.
+ * @param {string} projectRoot - Project root directory
+ * @param {number} [count=10] - Number of commits to retrieve
+ * @returns {Array<{hash: string, message: string}>}
+ */
+function getRecentCommits(projectRoot, count = 10) {
+  const output = git(`log --oneline -${count}`, projectRoot);
+  if (!output) return [];
+  return output.split('\n').filter(Boolean).map((line) => {
+    const spaceIndex = line.indexOf(' ');
+    return {
+      hash: line.slice(0, spaceIndex),
+      message: line.slice(spaceIndex + 1),
+    };
+  });
+}
+
+/**
+ * Check if a directory is inside a git repository.
+ * @param {string} dir - Directory to check
+ * @returns {boolean}
+ */
+function isGitRepo(dir) {
+  return git('rev-parse --is-inside-work-tree', dir) === 'true';
+}
+
+/**
+ * Get the git root directory.
+ * @param {string} dir - Directory to start from
+ * @returns {string|null} Git root path or null
+ */
+function getGitRoot(dir) {
+  return git('rev-parse --show-toplevel', dir);
+}
+
+/**
+ * Get the remote origin URL.
+ * @param {string} projectRoot - Project root directory
+ * @returns {string|null}
+ */
+function getRemoteUrl(projectRoot) {
+  return git('remote get-url origin', projectRoot);
+}
+
+module.exports = {
+  getGitCommit,
+  getGitCommitFull,
+  getGitBranch,
+  hasUncommittedChanges,
+  getChangedFiles,
+  getRecentCommits,
+  isGitRepo,
+  getGitRoot,
+  getRemoteUrl,
+};

package/lib/init.cjs

@@ -0,0 +1,370 @@
+/**
+ * GTD Init Module — Assembles workflow context for agent orchestration.
+ *
+ * Each workflow type receives a tailored context payload containing only
+ * the data it needs. This keeps agent prompts focused and avoids
+ * loading unnecessary context into limited token windows.
+ *
+ * @module lib/init
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { findProjectRoot, fileExists, readFileOr, ensureDir } = require('./file-ops.cjs');
+const { loadConfig } = require('./config.cjs');
+const { loadState } = require('./state.cjs');
+const { getAnalysisStatus, getCodebaseMapStatus } = require('./analysis.cjs');
+const {
+  getGitCommit,
+  getGitBranch,
+  hasUncommittedChanges,
+  isGitRepo,
+  getRemoteUrl,
+} = require('./git.cjs');
+
+/**
+ * Workflow → required context dimensions mapping.
+ * Each workflow only gets the context slices it needs.
+ */
+const WORKFLOW_CONTEXT = {
+  // Backward workflows
+  'scan-codebase': ['config', 'state', 'git'],
+  'analyze-codebase': ['config', 'state', 'git', 'codebase_map', 'analysis_status'],
+  'generate-document': ['config', 'state', 'git', 'codebase_map', 'analysis_status', 'doc_status'],
+  'create-all': ['config', 'state', 'git', 'codebase_map', 'analysis_status', 'doc_status'],
+  'verify-document': ['config', 'state', 'git', 'doc_status'],
+  'review-document': ['config', 'state', 'doc_status'],
+  'incremental-update': ['config', 'state', 'git', 'analysis_status', 'doc_status', 'git_diff'],
+
+  // Forward workflows
+  'new-project': ['config', 'state', 'git', 'codebase_map'],
+  'discuss-phase': ['config', 'state', 'git', 'roadmap', 'phase_context'],
+  'plan-phase': ['config', 'state', 'git', 'roadmap', 'phase_context', 'research'],
+  'execute-phase': ['config', 'state', 'git', 'roadmap', 'phase_context', 'plans'],
+  'verify-work': ['config', 'state', 'git', 'roadmap', 'phase_context', 'plans', 'summaries'],
+  'deploy-local': ['config', 'state', 'git', 'codebase_map'],
+  'test-phase': ['config', 'state', 'git', 'phase_context'],
+  ship: ['config', 'state', 'git'],
+
+  // Sync workflows
+  'detect-drift': ['config', 'state', 'git', 'analysis_status', 'doc_status', 'roadmap'],
+  reconcile: ['config', 'state', 'git', 'drift_report'],
+  sync: ['config', 'state', 'git', 'drift_report'],
+  audit: ['config', 'state', 'git', 'analysis_status', 'doc_status', 'roadmap'],
+
+  // Utility workflows
+  help: ['config', 'state'],
+  status: ['config', 'state', 'analysis_status', 'doc_status'],
+  settings: ['config'],
+};
+
+/**
+ * Main init function — assembles context for a workflow.
+ *
+ * @param {string[]} args - [workflowName, ...workflowArgs]
+ * @returns {void} Writes JSON to stdout
+ */
+function init(args) {
+  const workflowName = args[0];
+  const workflowArgs = args.slice(1);
+
+  if (!workflowName) {
+    process.stderr.write('Usage: gtd-tools.cjs init <workflow> [args...]\n');
+    process.exit(1);
+  }
+
+  const projectRoot = findProjectRoot(process.cwd()) || process.cwd();
+  const docsRoot = path.join(projectRoot, '.planning');
+
+  // Base context — always present
+  const context = {
+    project_root: projectRoot,
+    docs_root: docsRoot,
+    workflow: workflowName,
+    args: parseWorkflowArgs(workflowName, workflowArgs),
+    timestamp: new Date().toISOString(),
+    gtd_version: getGtdVersion(),
+  };
+
+  // Determine which context slices this workflow needs
+  const needed = WORKFLOW_CONTEXT[workflowName] || ['config', 'state', 'git'];
+
+  // Load each needed context slice
+  if (needed.includes('config')) {
+    context.config = loadConfig(docsRoot);
+  }
+
+  if (needed.includes('state')) {
+    context.state = loadState(docsRoot);
+  }
+
+  if (needed.includes('git')) {
+    context.git = buildGitContext(projectRoot);
+  }
+
+  if (needed.includes('codebase_map')) {
+    context.codebase_map = getCodebaseMapStatus(docsRoot);
+  }
+
+  if (needed.includes('analysis_status')) {
+    context.analysis_status = getAnalysisStatus(docsRoot);
+  }
+
+  if (needed.includes('doc_status')) {
+    const state = context.state || loadState(docsRoot);
+    context.documents = state.backward.documents;
+  }
+
+  if (needed.includes('roadmap')) {
+    context.roadmap = loadArtifact(docsRoot, 'ROADMAP.md');
+  }
+
+  if (needed.includes('phase_context')) {
+    context.phase = loadPhaseContext(docsRoot, context.args);
+  }
+
+  if (needed.includes('plans')) {
+    context.plans = loadPhasePlans(docsRoot, context.args);
+  }
+
+  if (needed.includes('research')) {
+    context.research = loadResearchSummary(docsRoot);
+  }
+
+  if (needed.includes('drift_report')) {
+    context.drift_report = loadArtifact(docsRoot, 'DRIFT-REPORT.md');
+  }
+
+  // Resolve model tiers for this workflow
+  if (context.config) {
+    context.models = resolveModelsForWorkflow(workflowName, context.config);
+  }
+
+  // Output context
+  outputContext(context);
+}
+
+/**
+ * Build git context object.
+ */
+function buildGitContext(projectRoot) {
+  if (!isGitRepo(projectRoot)) {
+    return { available: false };
+  }
+
+  return {
+    available: true,
+    commit: getGitCommit(projectRoot),
+    branch: getGitBranch(projectRoot),
+    has_changes: hasUncommittedChanges(projectRoot),
+    remote_url: getRemoteUrl(projectRoot),
+  };
+}
+
+/**
+ * Parse workflow-specific arguments.
+ */
+function parseWorkflowArgs(workflowName, args) {
+  const parsed = { raw: args };
+
+  // Extract common flags
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--auto' || arg === '-a') parsed.auto = true;
+    else if (arg === '--force' || arg === '-f') parsed.force = true;
+    else if (arg === '--parallel') parsed.parallel = true;
+    else if (arg === '--deep') parsed.deep = true;
+    else if (arg === '--format' && args[i + 1]) { parsed.format = args[++i]; }
+    else if (arg === '--since' && args[i + 1]) { parsed.since = args[++i]; }
+    else if (arg === '--focus' && args[i + 1]) { parsed.focus = args[++i]; }
+    else if (arg === '--module' && args[i + 1]) { parsed.module = args[++i]; }
+    else if (arg === '--wave' && args[i + 1]) { parsed.wave = parseInt(args[++i], 10); }
+    else if (arg === '--strategy' && args[i + 1]) { parsed.strategy = args[++i]; }
+    else if (arg === '--direction' && args[i + 1]) { parsed.direction = args[++i]; }
+    else if (arg === '--include-tests') parsed.include_tests = true;
+    else if (!arg.startsWith('-') && !parsed.positional) {
+      parsed.positional = arg;
+    }
+  }
+
+  // Workflow-specific positional arg interpretation
+  if (parsed.positional) {
+    if (['generate-document', 'verify-document', 'review-document'].includes(workflowName)) {
+      parsed.doc_type = parsed.positional;
+    } else if (
+      ['discuss-phase', 'plan-phase', 'execute-phase', 'verify-work', 'test-phase'].includes(
+        workflowName,
+      )
+    ) {
+      parsed.phase_number = parseInt(parsed.positional, 10);
+    }
+  }
+
+  return parsed;
+}
+
+/**
+ * Load a planning artifact as a string (or null if missing).
+ */
+function loadArtifact(docsRoot, filename) {
+  const filepath = path.join(docsRoot, filename);
+  if (!fileExists(filepath)) return null;
+  try {
+    return fs.readFileSync(filepath, 'utf8');
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Load phase-specific context files.
+ */
+function loadPhaseContext(docsRoot, args) {
+  const phaseNum = args.phase_number;
+  if (!phaseNum) return null;
+
+  const phasesDir = path.join(docsRoot, 'phases');
+  if (!fs.existsSync(phasesDir)) return { phase_number: phaseNum, exists: false };
+
+  // Find the phase directory (zero-padded: 01-, 02-, etc.)
+  const padded = String(phaseNum).padStart(2, '0');
+  const entries = fs.existsSync(phasesDir) ? fs.readdirSync(phasesDir) : [];
+  const phaseDir = entries.find((e) => e.startsWith(padded + '-'));
+
+  if (!phaseDir) return { phase_number: phaseNum, exists: false };
+
+  const fullPhaseDir = path.join(phasesDir, phaseDir);
+
+  return {
+    phase_number: phaseNum,
+    exists: true,
+    directory: fullPhaseDir,
+    context_file: loadArtifact(fullPhaseDir, `${padded}-CONTEXT.md`),
+    research_file: loadArtifact(fullPhaseDir, `${padded}-RESEARCH.md`),
+  };
+}
+
+/**
+ * Load plan files from a phase directory.
+ */
+function loadPhasePlans(docsRoot, args) {
+  const phaseNum = args.phase_number;
+  if (!phaseNum) return null;
+
+  const padded = String(phaseNum).padStart(2, '0');
+  const phasesDir = path.join(docsRoot, 'phases');
+  if (!fs.existsSync(phasesDir)) return [];
+
+  const entries = fs.readdirSync(phasesDir);
+  const phaseDir = entries.find((e) => e.startsWith(padded + '-'));
+  if (!phaseDir) return [];
+
+  const fullPhaseDir = path.join(phasesDir, phaseDir);
+  const allFiles = fs.readdirSync(fullPhaseDir);
+  const planFiles = allFiles.filter((f) => f.includes('-PLAN') && f.endsWith('.md'));
+
+  return planFiles.map((f) => ({
+    filename: f,
+    path: path.join(fullPhaseDir, f),
+  }));
+}
+
+/**
+ * Load research summary if available.
+ */
+function loadResearchSummary(docsRoot) {
+  const researchDir = path.join(docsRoot, 'research');
+  if (!fs.existsSync(researchDir)) return null;
+
+  return {
+    summary: loadArtifact(researchDir, 'SUMMARY.md'),
+    stack: loadArtifact(researchDir, 'STACK.md'),
+    features: loadArtifact(researchDir, 'FEATURES.md'),
+    architecture: loadArtifact(researchDir, 'ARCHITECTURE.md'),
+    pitfalls: loadArtifact(researchDir, 'PITFALLS.md'),
+  };
+}
+
+/**
+ * Resolve model tiers for agents used in this workflow.
+ */
+function resolveModelsForWorkflow(workflowName, config) {
+  const models = config.models || {};
+  const backwardWorkflows = [
+    'scan-codebase',
+    'analyze-codebase',
+    'generate-document',
+    'create-all',
+    'verify-document',
+    'review-document',
+    'incremental-update',
+  ];
+  const forwardWorkflows = [
+    'new-project',
+    'discuss-phase',
+    'plan-phase',
+    'execute-phase',
+    'verify-work',
+    'deploy-local',
+    'test-phase',
+    'ship',
+  ];
+
+  if (backwardWorkflows.includes(workflowName)) {
+    return {
+      analyzer: models.analyzer || 'sonnet',
+      writer: models.writer || 'sonnet',
+      verifier: models.verifier || 'haiku',
+    };
+  }
+
+  if (forwardWorkflows.includes(workflowName)) {
+    return {
+      researcher: models.researcher || 'sonnet',
+      planner: models.planner || 'sonnet',
+      executor: models.executor || 'sonnet',
+      verifier: models.verifier || 'haiku',
+    };
+  }
+
+  return models;
+}
+
+/**
+ * Output context as JSON, using @file: for large payloads.
+ */
+function outputContext(context) {
+  const json = JSON.stringify(context, null, 2);
+
+  if (json.length > 50000) {
+    // Write to temp file to avoid overwhelming stdout
+    const tmpDir = path.join(os.tmpdir(), 'gtd');
+    ensureDir(tmpDir);
+    const tmpFile = path.join(tmpDir, `init-${Date.now()}.json`);
+    fs.writeFileSync(tmpFile, json, 'utf8');
+    process.stdout.write(`@file:${tmpFile}`);
+  } else {
+    process.stdout.write(json);
+  }
+}
+
+/**
+ * Get the GTD package version.
+ */
+function getGtdVersion() {
+  try {
+    const pkg = require('../package.json');
+    return pkg.version;
+  } catch (_) {
+    return 'unknown';
+  }
+}
+
+module.exports = init;
+module.exports.buildGitContext = buildGitContext;
+module.exports.parseWorkflowArgs = parseWorkflowArgs;
+module.exports.WORKFLOW_CONTEXT = WORKFLOW_CONTEXT;