deuk-agent-flow 4.0.19

package/scripts/cli.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+import { existsSync, rmSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { parseArgs, parseTicketArgs, parseSkillArgs, parseTelemetryArgs, parseUsageArgs } from "./cli-args.mjs";
+import { runInit, runMerge } from "./cli-init-commands.mjs";
+import { runTicketCreate, runTicketList, runTicketUse, runTicketClose, runTicketArchive, runTicketDiscard, runTicketReports, runTicketMeta, runTicketConnect, runTicketRebuild, runTicketReportAttach, runTicketMove, runTicketNext, runTicketHotfix, runTicketStatus, runTicketGuard, runTicketHandoff, runTicketEvidenceCheck, runTicketEvidenceReport } from "./cli-ticket-commands.mjs";
+import { runTelemetry } from "./cli-telemetry-commands.mjs";
+import { runUsage } from "./cli-usage-commands.mjs";
+import { performUpgradeMigration } from "./cli-ticket-migration.mjs";
+import { loadInitConfig, writeInitConfig, checkUpdateNotifier, normalizeWorkflowMode, WORKFLOW_MODE_EXECUTE, AGENT_ROOT_DIR, resolveWorkflowMode, LEGACY_TEMPLATE_DIR, LEGACY_CONFIG_FILE } from "./cli-utils.mjs";
+import { runInteractive } from "./cli-prompts.mjs";
+
+const updatePromise = checkUpdateNotifier();
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = join(__dirname, "..");
+async function main() {
+  const argv = process.argv.slice(2);
+  const sub = argv[0];
+  if (!sub || sub === "-h" || sub === "--help" || sub === "help") {
+    printHelp();
+    return;
+  }
+
+  const rest = argv.slice(1);
+
+  if (sub === "ticket") {
+    const action = rest[0];
+    const opts = parseTicketArgs(rest.slice(1));
+    if (action === "create") await runTicketCreate(opts);
+    else if (action === "list") await runTicketList(opts);
+    else if (action === "use") await runTicketUse(opts);
+    else if (action === "next") await runTicketNext(opts);
+    else if (action === "evidence") await runTicketEvidenceCheck(opts);
+    else if (action === "close") await runTicketClose(opts);
+    else if (action === "archive") await runTicketArchive(opts);
+    else if (action === "discard" || action === "delete") await runTicketDiscard(opts);
+    else if (action === "reports") await runTicketReports(opts);
+    else if (action === "meta") await runTicketMeta(opts);
+    else if (action === "connect") await runTicketConnect(opts);
+    else if (action === "rebuild") await runTicketRebuild(opts);
+    else if (action === "move" || action === "step") await runTicketMove(opts);
+    else if (action === "hotfix") await runTicketHotfix(opts);
+    else if (action === "status") await runTicketStatus(opts);
+    else if (action === "guard" || action === "context") await runTicketGuard(opts);
+    else if (action === "handoff" || action === "continue") await runTicketHandoff(opts);
+    else if (action === "report") {
+      const subAction = rest[1];
+      if (subAction === "attach") {
+        const attachOpts = parseTicketArgs(rest.slice(2));
+        await runTicketReportAttach(attachOpts);
+      } else if (opts.claim) {
+        await runTicketEvidenceReport(opts);
+      } else {
+        await runTicketReports(opts);
+      }
+    }
+    else if (action === "upgrade" || action === "migrate") {
+      const count = performUpgradeMigration(opts.cwd, opts);
+      console.log(`Migration complete: ${count} tickets upgraded.`);
+    }
+    else {
+      console.error("Unknown ticket action: " + action);
+      printHelp();
+    }
+    return;
+  }
+
+  if (sub === "telemetry") {
+    const opts = parseTelemetryArgs(rest);
+    await runTelemetry(opts);
+    return;
+  }
+
+  if (sub === "usage") {
+    const action = rest[0];
+    const opts = parseUsageArgs(rest.slice(1));
+    await runUsage(action, opts);
+    return;
+  }
+
+  if (sub === "skill") {
+    const action = rest[0];
+    const opts = parseSkillArgs(rest.slice(1));
+    const { runSkill } = await import("./cli-skill-commands.mjs");
+    await runSkill(action, opts);
+    return;
+  }
+
+  if (sub === "lint:md" || sub === "lint-md") {
+    const { runMarkdownLint } = await import("./lint-md.mjs");
+    runMarkdownLint(rest);
+    return;
+  }
+
+  if (sub === "rules") {
+    const action = rest[0];
+    const opts = parseArgs(rest.slice(1));
+    if (action === "audit") {
+      const { runRulesAudit } = await import("./lint-rules.mjs");
+      runRulesAudit(opts);
+      return;
+    }
+    console.error("Unknown rules action: " + action);
+    printHelp();
+    return;
+  }
+
+  if (sub === "init" || sub === "merge") {
+    const opts = parseArgs(rest);
+    if (opts.help) {
+      printHelp();
+      return;
+    }
+
+    const saved = loadInitConfig(opts.cwd);
+    if (saved && !opts.interactive) {
+      // CLI flags (opts) take precedence over saved config
+      for (const key in saved) {
+        if (opts[key] === undefined) opts[key] = saved[key];
+      }
+      console.log(`Using saved config from ${AGENT_ROOT_DIR}/config.json (CLI overrides applied)`);
+    }
+
+    if (sub === "init") {
+      await handleInit(opts, saved);
+    } else {
+      runMerge(opts, pkgRoot);
+    }
+    return;
+  }
+
+  console.error("Unknown command: " + sub);
+  printHelp();
+}
+
+// Removed legacy migration runTicketMigrate
+
+async function handleInit(opts, saved) {
+  if (opts.clean && !opts.dryRun) {
+    console.log(`[CLEAN] Removing legacy templates and config...`);
+    const templatesDir = join(opts.cwd, LEGACY_TEMPLATE_DIR);
+    const configFile = join(opts.cwd, LEGACY_CONFIG_FILE);
+    if (existsSync(templatesDir)) rmSync(templatesDir, { recursive: true, force: true });
+    if (existsSync(configFile)) rmSync(configFile, { force: true });
+  }
+
+  if (!opts.interactive && !opts.nonInteractive && !saved) {
+    // If no config and not interactive, prompt unless non-interactive
+    await runInteractive(opts);
+  } else if (opts.interactive) {
+    await runInteractive(opts);
+  }
+
+  if (!opts.dryRun) writeInitConfig(opts.cwd, opts);
+
+  const workflowMode = resolveWorkflowMode(opts, saved);
+  if (!opts.dryRun && workflowMode !== WORKFLOW_MODE_EXECUTE) {
+    console.log(`[WORKFLOW] Plan mode active. Re-run with --workflow execute or --approval approved to apply file mutations.`);
+    return;
+  }
+
+  await runInit(opts, pkgRoot);
+}
+
+function printHelp() {
+  console.log(`DeukAgentFlow CLI - Generalization Rules & Ticket Management
+
+Usage:
+  npx deuk-agent-flow init   [options]
+  npx deuk-agent-flow merge  [options]
+  npx deuk-agent-flow lint:md [--cwd <path>] [files...]
+  npx deuk-agent-flow rules audit [--compact|--json]
+  npx deuk-agent-flow skill <list|add|expose|lint> [options]
+  npx deuk-agent-flow ticket <create|evidence|list|status|guard|context|handoff|continue|use|close|archive|discard|delete|reports|migrate|upgrade|meta|connect|move> [options]
+  npx deuk-agent-flow telemetry <log|sync|summary|migrate> [options]
+  npx deuk-agent-flow usage <set|status|advise> [options]
+
+Options:
+  --cwd <path>          Target repo root
+  --dry-run             Print actions without writing
+  --non-interactive     CI/scripts mode: no prompts
+  --tag <id>            Custom marker ID (default: deuk-agent-rule)
+  --agents <mode>       inject | skip | overwrite
+  --cursorrules <mode>  inject | skip | overwrite
+  --workflow <mode>     plan | execute
+  --approval <state>    pending | approved (alias for workflow)
+  --docs-language <lang> auto | ko | en
+  --json                Output result in JSON format
+  --remote <url>        Temporary pipeline URL
+  --sync                Force enable remote sync
+  --no-sync             Force disable remote sync
+
+Skill Options:
+  --skill, --id <name>  Skill ID (safe-refactor|generated-file-guard|context-recall|project-pilot)
+  --platform <name>     Exposure target (claude|cursor)
+
+Ticket Options:
+  --topic, --id <name>  Ticket topic slug or ID
+  --group <name>        Ticket group (sub|main|discussion)
+  --project <name>      Project filter (DeukUI|DeukAgentFlow)
+  --submodule <name>    Submodule filter (DeukPack|DeukUI)
+  --docs-language <lang> auto | ko | en
+  --evidence <text>     Provide Phase 0 RAG evidence summary
+  --claim <text>        Validate or report only from ticket evidence matching this claim
+  --skip-phase0         Bypass Phase 0 RAG validation
+  --plan-body <text>    Create ticket with filled Phase 1 markdown body
+  --plan-body-file <p>  Read filled Phase 1 markdown from a file, or '-' for stdin
+  --content-file <path> Read extra ticket context from a file, or '-' for stdin
+  --require-filled      Enforce non-placeholder APC and compact plan content before create succeeds
+  --allow-placeholder   Opt out of strict create guard (legacy behavior)
+  --ticket-started      Confirm the clickable ticket-start line was shared before guard/context
+  --ticket-reviewed     Confirm the durable ticket body was reopened and reviewed before guard/context
+  --compact             Prefer one-line ticket outputs in automation flows
+  --status-detail       Include detailed reasons in ticket status output
+  --handoff             Emit compact handoff output for session continuation
+  --phase <number>      Explicitly set the phase number (e.g., --phase 2)
+  --next                Move to the next phase
+  --latest, -l          Use most recent ticket (default if no topic)
+  --path-only           Print only the file path
+  --json                Output result in JSON format
+
+Usage Options:
+  --platform <name>           Platform name (Codex/Copilot supported)
+  --client <name>             Client label for usage state/output
+  --agent-id <id>             Agent identifier for per-agent tracking
+  --weekly-remaining <pct>   Remaining weekly percentage (0-100)
+  --five-hour-remaining <pct> Remaining 5-hour percentage (0-100)
+  --weekly-reset <text>      Weekly reset time label
+  --five-hour-reset <text>   5-hour reset time label
+  --task-grade <grade>       Task grade (S|A|B|C)
+  --task <label>             Optional task label for advice output
+  --turn-count <n>           Conversation turn count for split advice
+  --linked-ticket-count <n>  Linked ticket count for split advice
+  --cross-workspace          Mark the conversation as cross-workspace
+`);
+}
+
+main().then(async () => {
+  await updatePromise;
+}).catch(async err => {
+  await updatePromise;
+  console.error(err.message || err);
+  process.exit(1);
+});

package/scripts/lint-md.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+import { readFileSync, readdirSync, statSync } from "fs";
+import { join, relative, dirname, resolve } from "path";
+import { spawnSync } from "child_process";
+import YAML from "yaml";
+import { AGENT_ROOT_DIR, TICKET_DIR_NAME } from "./cli-utils.mjs";
+
+const ignoredDirs = new Set([".git", "node_modules"]);
+
+export function collectChangedFiles(repoRoot) {
+  const changed = new Set();
+
+  const gitArgs = ["-C", repoRoot, "diff", "--name-only", "--diff-filter=ACMRTUXB"];
+  const gitDiff = spawnSync("git", gitArgs, { encoding: "utf8" });
+  if (gitDiff.status === 0) {
+    gitDiff.stdout
+      .split("\n")
+      .map(s => s.trim())
+      .filter(Boolean)
+      .forEach(f => changed.add(f));
+  }
+
+  const gitUntracked = spawnSync("git", ["-C", repoRoot, "ls-files", "--others", "--exclude-standard"], { encoding: "utf8" });
+  if (gitUntracked.status === 0) {
+    gitUntracked.stdout
+      .split("\n")
+      .map(s => s.trim())
+      .filter(Boolean)
+      .forEach(f => changed.add(f));
+  }
+
+  return Array.from(changed).sort();
+}
+
+export function collectChangedMarkdownFiles(repoRoot) {
+  return collectChangedFiles(repoRoot).filter(isMarkdownFile);
+}
+
+function isMarkdownFile(filePath) {
+  const lower = filePath.toLowerCase();
+  return lower.endsWith(".md") || lower.endsWith(".mdx") || lower.endsWith(".markdown");
+}
+
+function isPlanReport(relPath) {
+  return relPath.includes(`${AGENT_ROOT_DIR}/docs/plan/`) && relPath.endsWith("-report.md");
+}
+
+const LEGACY_ARCHIVED_TEMPLATE_NAMES = new Set([
+  "module-rule-template.md",
+  "ticket-list-template.md",
+  "ticket-template-ko.md",
+  "ticket-template.md"
+]);
+
+function isLegacyArchivedTemplateArtifact(relPath, content) {
+  const normalized = relPath.replace(/\\/g, "/");
+  if (!normalized.includes(`${TICKET_DIR_NAME}/archive/`)) return false;
+  if (!LEGACY_ARCHIVED_TEMPLATE_NAMES.has(normalized.split("/").pop())) return false;
+
+  const src = String(content || "");
+  return src.includes("<%=") || src.includes("<%-") || /^id:\s*(module-rule-template|ticket-list-template|ticket-template-ko|ticket-template)\s*$/m.test(src);
+}
+
+function looksLikeYamlFrontmatter(content) {
+  if (!(content.startsWith("---\n") || content.startsWith("---\r\n"))) return false;
+  const afterOpening = content.replace(/^---\r?\n/, "");
+  const lines = afterOpening.split(/\r?\n/);
+  const frontmatterLines = [];
+
+  for (const line of lines) {
+    if (line.trim() === "---") break;
+    frontmatterLines.push(line);
+  }
+
+  if (frontmatterLines.length === 0) return false;
+
+  const firstNonEmpty = frontmatterLines.find(line => line.trim());
+  if (!firstNonEmpty) return false;
+  if (/^(#|>|- |\* |\d+\.)/.test(firstNonEmpty.trim())) return false;
+
+  return frontmatterLines.some(line => /^[A-Za-z0-9_-]+\s*:/.test(line.trim()));
+}
+
+function lintWalkthroughReportStructure(relPath, content) {
+  const errors = [];
+  const hasSummary = /##\s+(Summary|요약)(?:\s|$)/i.test(content);
+  const hasVerification = /##\s+(Verification|검증)(?:\s|$)/i.test(content);
+  const hasOutcome = /##\s+(Verification Outcome|Verification Results|검증 결과)(?:\s|$)/i.test(content);
+
+  if (!hasSummary) {
+    errors.push(`${relPath}: report missing Summary/요약 section`);
+  }
+  if (!hasVerification) {
+    errors.push(`${relPath}: report missing Verification/검증 section`);
+  }
+  if (!hasOutcome) {
+    errors.push(`${relPath}: report missing Verification Outcome/Verification Results/검증 결과 section`);
+  }
+
+  return errors;
+}
+
+function walkMarkdownFiles(rootDir, out = []) {
+  for (const entry of readdirSync(rootDir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (ignoredDirs.has(entry.name)) continue;
+      walkMarkdownFiles(join(rootDir, entry.name), out);
+      continue;
+    }
+    const filePath = join(rootDir, entry.name);
+    if (isMarkdownFile(filePath)) out.push(filePath);
+  }
+  return out;
+}
+
+function lintFile(absPath, repoRoot) {
+  const rel = relative(repoRoot, absPath);
+  const content = readFileSync(absPath, "utf8");
+  const errors = [];
+
+  if (isLegacyArchivedTemplateArtifact(rel, content)) {
+    return errors;
+  }
+
+  const lines = content.split(/\r?\n/);
+  lines.forEach((line, idx) => {
+    if (/\s+$/.test(line)) {
+      errors.push(`${rel}:${idx + 1}: trailing whitespace`);
+    }
+  });
+
+  const fenceCount = lines.filter(line => /^```/.test(line.trim())).length;
+  if (fenceCount % 2 !== 0) {
+    errors.push(`${rel}: unmatched fenced code block`);
+  }
+
+  if (looksLikeYamlFrontmatter(content)) {
+    const match = content.match(/^---\r?\n([\s\S]+?)\r?\n---\r?\n?/);
+    if (!match) {
+      const afterOpeningRule = content.replace(/^---\r?\n/, "");
+      if (!/^\s*\r?\n#{1,6}\s/.test(afterOpeningRule)) {
+        errors.push(`${rel}: invalid or unterminated frontmatter`);
+      }
+    } else {
+      try {
+        const parsed = YAML.parse(match[1]);
+        const isDeukAgentDoc = rel.includes(`${AGENT_ROOT_DIR}/docs/`) || rel.includes(`${AGENT_ROOT_DIR}/tickets/`);
+        const isArchive = rel.includes("archive/");
+        const isTemplate = rel.includes("templates/");
+        if (isDeukAgentDoc && !isArchive && !isTemplate) {
+          const requiredKeys = ["summary", "status", "priority", "tags"];
+          for (const key of requiredKeys) {
+            if (!parsed || parsed[key] === undefined || parsed[key] === null || parsed[key] === "") {
+              errors.push(`${rel}: missing required frontmatter key: ${key}`);
+            }
+          }
+        }
+      } catch (err) {
+        errors.push(`${rel}: invalid frontmatter YAML (${err.message})`);
+      }
+    }
+  } else {
+    const isDeukAgentDoc = rel.includes(`${AGENT_ROOT_DIR}/docs/`) || rel.includes(`${AGENT_ROOT_DIR}/tickets/`);
+    const isArchive = rel.includes("archive/");
+    const isTemplate = rel.includes("templates/");
+    if (isDeukAgentDoc && !isArchive && !isTemplate) {
+      errors.push(`${rel}: missing required frontmatter`);
+    }
+  }
+
+  const linkPattern = /!?\[[^\]]+\]\(([^)]+)\)/g;
+  let match;
+  while ((match = linkPattern.exec(content)) !== null) {
+    const target = String(match[1] || "").trim();
+    if (!target || target.startsWith("#") || /^[a-z]+:\/\//i.test(target) || target.startsWith("mailto:")) {
+      continue;
+    }
+    const pathOnly = target.split("#")[0].split("?")[0];
+    if (!pathOnly) continue;
+    const resolved = join(dirname(absPath), pathOnly);
+    if (!statExists(resolved)) {
+      errors.push(`${rel}: broken relative link -> ${target}`);
+    }
+  }
+
+  if (isPlanReport(rel)) {
+    errors.push(...lintWalkthroughReportStructure(rel, content));
+  }
+
+  return errors;
+}
+
+function statExists(absPath) {
+  try {
+    return statSync(absPath).isFile() || statSync(absPath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function resolveMarkdownLintTargets(repoRoot, explicitPaths = []) {
+  const files = explicitPaths.length > 0
+    ? explicitPaths.map(p => resolve(repoRoot, p)).filter(statExists).filter(isMarkdownFile)
+    : collectChangedMarkdownFiles(repoRoot).map(p => join(repoRoot, p));
+
+  const targets = files.length > 0 ? files : walkMarkdownFiles(repoRoot);
+  return Array.from(new Set(targets));
+}
+
+function parseLintArgs(argv) {
+  const out = { cwd: process.cwd(), paths: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--cwd") {
+      out.cwd = argv[++i] || out.cwd;
+    } else if (arg.startsWith("--cwd=")) {
+      out.cwd = arg.slice("--cwd=".length);
+    } else if (!arg.startsWith("-")) {
+      out.paths.push(arg);
+    }
+  }
+  return out;
+}
+
+export function lintMarkdownPaths(paths, cwd = process.cwd()) {
+  const repoRoot = resolve(cwd);
+  const targets = Array.from(new Set(
+    (Array.isArray(paths) ? paths : [])
+      .map(p => resolve(repoRoot, p))
+      .filter(statExists)
+      .filter(isMarkdownFile)
+  ));
+  const errors = [];
+  for (const filePath of targets) {
+    errors.push(...lintFile(filePath, repoRoot));
+  }
+  return { repoRoot, targets, errors };
+}
+
+export function runMarkdownLint(argv = process.argv.slice(2)) {
+  const opts = parseLintArgs(argv);
+  const repoRoot = resolve(opts.cwd);
+  const targets = opts.paths.length > 0
+    ? lintMarkdownPaths(opts.paths, opts.cwd).targets
+    : resolveMarkdownLintTargets(repoRoot);
+  const errors = [];
+  for (const filePath of targets) {
+    errors.push(...lintFile(filePath, repoRoot));
+  }
+
+  if (targets.length === 0) {
+    console.log("lint:md: no markdown files found");
+    return;
+  }
+
+  if (errors.length > 0) {
+    console.error("lint:md failed");
+    for (const err of errors) console.error(`- ${err}`);
+    process.exit(1);
+  }
+
+  console.log(`lint:md passed (${targets.length} file${targets.length === 1 ? "" : "s"})`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  runMarkdownLint();
+}