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

package/sdk/src/query/detect-phase-type.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Unit tests for `detect.phase-type` (decision-routing audit §3.6).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { detectPhaseType } from './detect-phase-type.js';
+
+describe('detectPhaseType', () => {
+  let projectDir: string;
+
+  beforeEach(async () => {
+    projectDir = join(tmpdir(), `gtd-detect-phase-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(join(projectDir, '.planning', 'phases'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(projectDir, { recursive: true, force: true });
+  });
+
+  it('throws when phase arg is missing', async () => {
+    await expect(detectPhaseType([], projectDir)).rejects.toThrow();
+  });
+
+  it('returns all false/null/[] when phase dir does not exist', async () => {
+    const { data } = await detectPhaseType(['99'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(d.has_frontend).toBe(false);
+    expect(d.has_schema).toBe(false);
+    expect(d.schema_orm).toBeNull();
+    expect(d.schema_files).toEqual([]);
+    expect(d.frontend_indicators).toEqual([]);
+    expect(d.has_api).toBe(false);
+    expect(d.has_infra).toBe(false);
+  });
+
+  it('sets has_frontend true when ROADMAP heading contains UI keyword', async () => {
+    const roadmapContent = `# Project Roadmap\n\n## Phase 01: UI Dashboard\n\nSome content\n`;
+    await writeFile(join(projectDir, '.planning', 'ROADMAP.md'), roadmapContent, 'utf-8');
+    await mkdir(join(projectDir, '.planning', 'phases', '01-ui-dashboard'), { recursive: true });
+
+    const { data } = await detectPhaseType(['1'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(d.has_frontend).toBe(true);
+    expect((d.frontend_indicators as string[]).length).toBeGreaterThan(0);
+  });
+
+  it('sets has_schema true and schema_orm prisma when prisma schema file found', async () => {
+    const phaseDir = join(projectDir, '.planning', 'phases', '02-database');
+    await mkdir(join(phaseDir, 'prisma'), { recursive: true });
+    await writeFile(join(phaseDir, 'prisma', 'schema.prisma'), 'model User {}', 'utf-8');
+
+    const { data } = await detectPhaseType(['2'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(d.has_schema).toBe(true);
+    expect(d.schema_orm).toBe('prisma');
+    expect((d.schema_files as string[]).length).toBeGreaterThan(0);
+  });
+
+  it('sets has_frontend true when UI-SPEC.md is present in phase dir', async () => {
+    const phaseDir = join(projectDir, '.planning', 'phases', '03-features');
+    await mkdir(phaseDir, { recursive: true });
+    await writeFile(join(phaseDir, 'UI-SPEC.md'), '# UI Spec', 'utf-8');
+
+    const { data } = await detectPhaseType(['3'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(d.has_frontend).toBe(true);
+  });
+
+  it('sets has_api true when route file found in phase dir', async () => {
+    const phaseDir = join(projectDir, '.planning', 'phases', '04-api');
+    await mkdir(phaseDir, { recursive: true });
+    await writeFile(join(phaseDir, 'user.route.ts'), 'export {}', 'utf-8');
+
+    const { data } = await detectPhaseType(['4'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(d.has_api).toBe(true);
+  });
+
+  it('sets has_infra true when docker file found in phase dir', async () => {
+    const phaseDir = join(projectDir, '.planning', 'phases', '05-infra');
+    await mkdir(phaseDir, { recursive: true });
+    await writeFile(join(phaseDir, 'dockerfile.yml'), '', 'utf-8');
+
+    const { data } = await detectPhaseType(['5'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(d.has_infra).toBe(true);
+  });
+
+  it('returns push_command null (reserved field)', async () => {
+    await mkdir(join(projectDir, '.planning', 'phases', '06-misc'), { recursive: true });
+    const { data } = await detectPhaseType(['6'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(d.push_command).toBeNull();
+  });
+
+  it('returns correct phase field in output', async () => {
+    await mkdir(join(projectDir, '.planning', 'phases', '07-test'), { recursive: true });
+    const { data } = await detectPhaseType(['7'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(d.phase).toBe('07');
+  });
+});

package/sdk/src/query/detect-phase-type.ts

@@ -0,0 +1,141 @@
+/**
+ * Phase type detection (`detect.phase-type`).
+ *
+ * Replaces fragile grep-based UI/schema/API detection in workflows with a
+ * structured query. See `.planning/research/decision-routing-audit.md` §3.6.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { GTDError, ErrorClassification } from '../errors.js';
+import { escapeRegex, normalizePhaseName, planningPaths } from './helpers.js';
+import { findPhase } from './phase.js';
+import { detectSchemaFiles } from './schema-detect.js';
+import type { QueryHandler } from './utils.js';
+
+// Copied from phase-ready.ts — do not import to avoid cross-module coupling.
+const UI_INDICATOR_RE = /UI|interface|frontend|component|layout|page|screen|view|form|dashboard|widget/i;
+
+const API_INDICATOR_RE = /route\.ts|controller\.|api\//i;
+const API_HEADING_RE = /\bAPI\b|endpoint|REST|GraphQL/i;
+const INFRA_RE = /docker|terraform|k8s|helm|infra/i;
+
+async function roadmapHeadingForPhase(projectDir: string, phaseNum: string, workstream?: string): Promise<string | null> {
+  const roadmapPath = planningPaths(projectDir, workstream).roadmap;
+  let content: string;
+  try {
+    content = await readFile(roadmapPath, 'utf-8');
+  } catch {
+    return null;
+  }
+  const re = new RegExp(`#{2,4}\\s*Phase\\s+${escapeRegex(phaseNum)}\\s*:[^\\n]*`, 'i');
+  const m = content.match(re);
+  return m ? m[0] : null;
+}
+
+export const detectPhaseType: QueryHandler = async (args, projectDir, workstream) => {
+  const raw = args[0];
+  if (!raw) {
+    throw new GTDError('phase number required for detect phase-type', ErrorClassification.Validation);
+  }
+  const phaseArg = normalizePhaseName(raw);
+
+  const phaseRes = await findPhase([raw], projectDir, workstream);
+  const pdata = phaseRes.data as Record<string, unknown>;
+  const found = Boolean(pdata.found);
+
+  // Build phase dir absolute path when found
+  let phaseDirFull: string | null = null;
+  if (found && pdata.directory) {
+    phaseDirFull = join(projectDir, pdata.directory as string);
+  }
+
+  const phaseNumForRoadmap = (pdata.phase_number as string) || phaseArg;
+
+  // Read ROADMAP heading — try both normalized forms
+  let heading = await roadmapHeadingForPhase(projectDir, phaseNumForRoadmap, workstream);
+  if (!heading && phaseNumForRoadmap !== phaseArg) {
+    heading = await roadmapHeadingForPhase(projectDir, phaseArg, workstream);
+  }
+
+  // Frontend detection
+  const headingUiMatch = heading ? UI_INDICATOR_RE.test(heading) : false;
+  const frontendIndicators: string[] = [];
+
+  if (heading && headingUiMatch) {
+    // Collect matched keywords from heading
+    const keywords = ['UI', 'interface', 'frontend', 'component', 'layout', 'page', 'screen', 'view', 'form', 'dashboard', 'widget'];
+    for (const kw of keywords) {
+      if (new RegExp(`\\b${kw}\\b`, 'i').test(heading)) {
+        frontendIndicators.push(kw);
+      }
+    }
+  }
+
+  let hasUiSpecFile = false;
+  let dirFiles: string[] = [];
+
+  if (phaseDirFull && existsSync(phaseDirFull)) {
+    try {
+      dirFiles = readdirSync(phaseDirFull, { recursive: false }) as string[];
+    } catch {
+      dirFiles = [];
+    }
+    hasUiSpecFile = dirFiles.some(f => f === 'UI-SPEC.md' || f.endsWith('-UI-SPEC.md'));
+  }
+
+  const has_frontend = headingUiMatch || hasUiSpecFile;
+
+  // Schema detection — build relative paths from phase dir for detectSchemaFiles
+  let schemaFiles: string[] = [];
+  let schemaOrm: string | null = null;
+  let hasSchema = false;
+
+  if (phaseDirFull && dirFiles.length > 0) {
+    // Also check subdirectory one level deep (e.g. prisma/schema.prisma)
+    const allRelPaths: string[] = [...dirFiles];
+    for (const f of dirFiles) {
+      const sub = join(phaseDirFull, f);
+      if (existsSync(sub)) {
+        try {
+          const subStat = readdirSync(sub);
+          for (const sf of subStat) {
+            allRelPaths.push(`${f}/${sf}`);
+          }
+        } catch {
+          // Not a directory — ignore
+        }
+      }
+    }
+
+    const detection = detectSchemaFiles(allRelPaths);
+    if (detection.detected) {
+      hasSchema = true;
+      schemaFiles = detection.matches;
+      schemaOrm = detection.orms[0] ?? null;
+    }
+  }
+
+  // API detection
+  const apiFromFiles = dirFiles.some(f => API_INDICATOR_RE.test(f));
+  const apiFromHeading = heading ? API_HEADING_RE.test(heading) : false;
+  const has_api = apiFromFiles || apiFromHeading;
+
+  // Infra detection
+  const has_infra = dirFiles.some(f => INFRA_RE.test(f));
+
+  return {
+    data: {
+      phase: phaseArg,
+      has_frontend,
+      frontend_indicators: frontendIndicators,
+      has_schema: hasSchema,
+      schema_orm: schemaOrm,
+      schema_files: schemaFiles,
+      push_command: null,
+      has_api,
+      has_infra,
+    },
+  };
+};

package/sdk/src/query/docs-init.ts

@@ -0,0 +1,258 @@
+/**
+ * Docs-init — context bundle for the docs-update workflow.
+ *
+ * Full port of `cmdDocsInit` and helpers from `get-tasks-done/bin/lib/docs.cjs`.
+ */
+
+import {
+  closeSync,
+  existsSync,
+  openSync,
+  readFileSync,
+  readSync,
+  readdirSync,
+  statSync,
+  type Dirent,
+} from 'node:fs';
+import { join, relative } from 'node:path';
+
+import { loadConfig } from '../config.js';
+import { MODEL_PROFILES, resolveModel } from './config-query.js';
+import { detectRuntime, resolveAgentsDir, toPosixPath } from './helpers.js';
+import type { QueryHandler } from './utils.js';
+
+const GTD_MARKER = '<!-- generated-by: gtd-doc-writer -->';
+
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.planning', '.claude', '__pycache__',
+  'target', 'dist', 'build', '.next', '.nuxt', 'coverage',
+  '.vscode', '.idea',
+]);
+
+function pathExistsInternal(cwd: string, rel: string): boolean {
+  try {
+    return existsSync(join(cwd, rel));
+  } catch {
+    return false;
+  }
+}
+
+function hasGtdMarker(filePath: string): boolean {
+  try {
+    const buf = Buffer.alloc(500);
+    const fd = openSync(filePath, 'r');
+    const bytesRead = readSync(fd, buf, 0, 500, 0);
+    closeSync(fd);
+    return buf.subarray(0, bytesRead).toString('utf-8').includes(GTD_MARKER);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Recursively scan project root `.md` files and `docs/` (or fallbacks) up to depth 4.
+ * Port of `scanExistingDocs` from docs.cjs.
+ */
+export function scanExistingDocs(cwd: string): Array<{ path: string; has_gtd_marker: boolean }> {
+  const MAX_DEPTH = 4;
+  const results: Array<{ path: string; has_gtd_marker: boolean }> = [];
+
+  function walkDir(dir: string, depth: number): void {
+    if (depth > MAX_DEPTH) return;
+    try {
+      const entries = readdirSync(dir, { withFileTypes: true }) as Dirent[];
+      for (const entry of entries) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        const abs = join(dir, entry.name);
+        const nameStr = entry.name.toString();
+        if (entry.isDirectory()) {
+          walkDir(abs, depth + 1);
+        } else if (entry.isFile() && nameStr.toLowerCase().endsWith('.md')) {
+          const rel = toPosixPath(relative(cwd, abs));
+          results.push({ path: rel, has_gtd_marker: hasGtdMarker(abs) });
+        }
+      }
+    } catch { /* directory may not exist */ }
+  }
+
+  try {
+    const rootEntries = readdirSync(cwd, { withFileTypes: true }) as Dirent[];
+    for (const entry of rootEntries) {
+      const nameStr = entry.name.toString();
+      if (entry.isFile() && nameStr.toLowerCase().endsWith('.md')) {
+        const abs = join(cwd, nameStr);
+        const rel = toPosixPath(relative(cwd, abs));
+        results.push({ path: rel, has_gtd_marker: hasGtdMarker(abs) });
+      }
+    }
+  } catch { /* best-effort */ }
+
+  const docsDir = join(cwd, 'docs');
+  walkDir(docsDir, 1);
+
+  try {
+    statSync(docsDir);
+  } catch {
+    for (const alt of ['documentation', 'doc']) {
+      const altDir = join(cwd, alt);
+      try {
+        const st = statSync(altDir);
+        if (st.isDirectory()) {
+          walkDir(altDir, 1);
+          break;
+        }
+      } catch { /* not present */ }
+    }
+  }
+
+  return results.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/** Port of `detectProjectType` from docs.cjs. */
+export function detectProjectType(cwd: string): Record<string, boolean> {
+  const exists = (rel: string): boolean => pathExistsInternal(cwd, rel);
+
+  let has_cli_bin = false;
+  try {
+    const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf-8')) as Record<string, unknown>;
+    const bin = pkg.bin;
+    has_cli_bin = !!(bin && (typeof bin === 'string' || Object.keys(bin as object).length > 0));
+  } catch { /* no package.json */ }
+
+  let is_monorepo = exists('pnpm-workspace.yaml') || exists('lerna.json');
+  if (!is_monorepo) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf-8')) as Record<string, unknown>;
+      is_monorepo = Array.isArray(pkg.workspaces) && (pkg.workspaces as unknown[]).length > 0;
+    } catch { /* ignore */ }
+  }
+
+  let has_tests = exists('test') || exists('tests') || exists('__tests__') || exists('spec');
+  if (!has_tests) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf-8')) as Record<string, unknown>;
+      const devDeps = Object.keys((pkg.devDependencies as Record<string, unknown>) || {});
+      has_tests = devDeps.some(d => ['vitest', 'jest', 'mocha', 'jasmine', 'ava'].includes(d));
+    } catch { /* ignore */ }
+  }
+
+  const deployFiles = [
+    'Dockerfile', 'docker-compose.yml', 'docker-compose.yaml',
+    'fly.toml', 'render.yaml', 'vercel.json', 'netlify.toml', 'railway.json',
+    '.github/workflows/deploy.yml', '.github/workflows/deploy.yaml',
+  ];
+  const has_deploy_config = deployFiles.some(f => exists(f));
+
+  return {
+    has_package_json: exists('package.json'),
+    has_api_routes: (
+      exists('src/app/api') || exists('routes') || exists('src/routes') ||
+      exists('api') || exists('server')
+    ),
+    has_cli_bin,
+    is_open_source: exists('LICENSE') || exists('LICENSE.md'),
+    has_deploy_config,
+    is_monorepo,
+    has_tests,
+  };
+}
+
+/** Port of `detectDocTooling` from docs.cjs. */
+export function detectDocTooling(cwd: string): Record<string, boolean> {
+  const exists = (rel: string): boolean => pathExistsInternal(cwd, rel);
+  return {
+    docusaurus: exists('docusaurus.config.js') || exists('docusaurus.config.ts'),
+    vitepress: (
+      exists('.vitepress/config.js') ||
+      exists('.vitepress/config.ts') ||
+      exists('.vitepress/config.mts')
+    ),
+    mkdocs: exists('mkdocs.yml'),
+    storybook: exists('.storybook'),
+  };
+}
+
+/** Port of `detectMonorepoWorkspaces` from docs.cjs. */
+export function detectMonorepoWorkspaces(cwd: string): string[] {
+  try {
+    const content = readFileSync(join(cwd, 'pnpm-workspace.yaml'), 'utf-8');
+    const workspaces: string[] = [];
+    for (const line of content.split('\n')) {
+      const m = line.match(/^\s*-\s+['"]?(.+?)['"]?\s*$/);
+      if (m) workspaces.push(m[1].trim());
+    }
+    if (workspaces.length > 0) return workspaces;
+  } catch { /* not present */ }
+
+  try {
+    const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf-8')) as Record<string, unknown>;
+    if (Array.isArray(pkg.workspaces) && pkg.workspaces.length > 0) {
+      return pkg.workspaces as string[];
+    }
+  } catch { /* not present */ }
+
+  try {
+    const lerna = JSON.parse(readFileSync(join(cwd, 'lerna.json'), 'utf-8')) as { packages?: string[] };
+    if (Array.isArray(lerna.packages) && lerna.packages.length > 0) {
+      return lerna.packages;
+    }
+  } catch { /* not present */ }
+
+  return [];
+}
+
+/**
+ * Port of `checkAgentsInstalled` from core.cjs (same logic as init.ts).
+ */
+function checkAgentsInstalled(config?: { runtime?: unknown }): { agents_installed: boolean; missing_agents: string[] } {
+  const runtime = detectRuntime(config);
+  const agentsDir = resolveAgentsDir(runtime);
+  const expectedAgents = Object.keys(MODEL_PROFILES);
+
+  if (!existsSync(agentsDir)) {
+    return { agents_installed: false, missing_agents: expectedAgents };
+  }
+
+  const missing: string[] = [];
+  for (const agent of expectedAgents) {
+    const agentFile = join(agentsDir, `${agent}.md`);
+    const agentFileCopilot = join(agentsDir, `${agent}.agent.md`);
+    if (!existsSync(agentFile) && !existsSync(agentFileCopilot)) {
+      missing.push(agent);
+    }
+  }
+
+  return {
+    agents_installed: missing.length === 0,
+    missing_agents: missing,
+  };
+}
+
+/**
+ * Init payload for docs-update workflow — matches `gtd-tools docs-init` JSON.
+ * Port of `cmdDocsInit` from docs.cjs.
+ */
+export const docsInit: QueryHandler = async (_args, projectDir) => {
+  const config = await loadConfig(projectDir);
+  const configExists = existsSync(join(projectDir, '.planning', 'config.json'));
+  const docModelResult = await resolveModel(['gtd-doc-writer'], projectDir);
+  const docWriterData = docModelResult.data as Record<string, unknown>;
+  const doc_writer_model = configExists ? ((docWriterData?.model as string) || '') : '';
+
+  const agentStatus = checkAgentsInstalled(config as { runtime?: unknown });
+
+  const data: Record<string, unknown> = {
+    doc_writer_model,
+    commit_docs: config.commit_docs,
+    existing_docs: scanExistingDocs(projectDir),
+    project_type: detectProjectType(projectDir),
+    doc_tooling: detectDocTooling(projectDir),
+    monorepo_workspaces: detectMonorepoWorkspaces(projectDir),
+    planning_exists: pathExistsInternal(projectDir, '.planning'),
+    project_root: projectDir,
+    agents_installed: agentStatus.agents_installed,
+    missing_agents: agentStatus.missing_agents,
+  };
+
+  return { data };
+};

package/sdk/src/query/fallow-audit.ts

@@ -0,0 +1,88 @@
+export interface FallowUnusedExport {
+  file?: string;
+  symbol?: string;
+  line?: number | null;
+}
+
+export interface FallowDuplicateBlock {
+  left?: { file?: string; start?: number | null; end?: number | null };
+  right?: { file?: string; start?: number | null; end?: number | null };
+  similarity?: number;
+}
+
+export interface FallowCircularDependency {
+  cycle?: string[];
+}
+
+export interface FallowReport {
+  unusedExports?: FallowUnusedExport[];
+  duplicates?: FallowDuplicateBlock[];
+  circularDependencies?: FallowCircularDependency[];
+}
+
+export interface NormalizedFallowFinding {
+  type: 'unused_export' | 'duplicate_block' | 'circular_dependency';
+  message: string;
+  file: string;
+  line: number | null;
+  related_file?: string;
+}
+
+export interface NormalizedFallowReport {
+  summary: {
+    unused_exports: number;
+    duplicates: number;
+    circular_dependencies: number;
+    total: number;
+  };
+  findings: NormalizedFallowFinding[];
+}
+
+// TODO(parity): SDK lacks a TS test harness for normalizeFallowReport. CJS parity tests live in
+// tests/feat-3210-fallow-integration.test.cjs (H1 suite). When a TS test runner is added,
+// mirror those cases here — especially the line:0 preservation assertions.
+export function normalizeFallowReport(report: FallowReport | null | undefined): NormalizedFallowReport {
+  const unused = Array.isArray(report?.unusedExports) ? report.unusedExports : [];
+  const duplicates = Array.isArray(report?.duplicates) ? report.duplicates : [];
+  const circular = Array.isArray(report?.circularDependencies) ? report.circularDependencies : [];
+
+  const findings: NormalizedFallowFinding[] = [];
+
+  for (const item of unused) {
+    findings.push({
+      type: 'unused_export',
+      message: `Unused export ${item.symbol || '<unknown>'}`,
+      file: item.file || '',
+      line: item.line ?? null,
+    });
+  }
+
+  for (const item of duplicates) {
+    findings.push({
+      type: 'duplicate_block',
+      message: `Duplicate block (${Math.round((item.similarity || 0) * 100)}% similarity)`,
+      file: item.left?.file || '',
+      line: item.left?.start ?? null,
+      related_file: item.right?.file || '',
+    });
+  }
+
+  for (const item of circular) {
+    findings.push({
+      type: 'circular_dependency',
+      message: `Circular dependency: ${(item.cycle || []).join(' -> ')}`,
+      file: Array.isArray(item.cycle) && item.cycle.length > 0 ? item.cycle[0] : '',
+      line: null,
+    });
+  }
+
+  return {
+    summary: {
+      unused_exports: unused.length,
+      duplicates: duplicates.length,
+      circular_dependencies: circular.length,
+      total: findings.length,
+    },
+    findings,
+  };
+}

package/sdk/src/query/frontmatter-array.test.ts

@@ -0,0 +1,14 @@
+import { describe, it, expect } from 'vitest';
+import { extractFrontmatter } from './frontmatter.js';
+
+describe('extractFrontmatter array-of-objects', () => {
+  it('parses array of objects', () => {
+    const content = `---\nitems:\n  - id: 1\n    name: test\n  - id: 2\n    name: test2\n---\n`;
+    expect(extractFrontmatter(content)).toEqual({
+      items: [
+        { id: '1', name: 'test' },
+        { id: '2', name: 'test2' }
+      ]
+    });
+  });
+});