@specforge/cli 0.1.0

package/dist/cli/commands/scaffold/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/scaffold/types.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/scaffold/types.js

@@ -0,0 +1,12 @@
+const COMMAND_CATEGORIES = {
+  "Setup": ["sf-init", "sf-context"],
+  "Status": ["sf-status", "sf-analyze-blockers"],
+  "Review": ["sf-search"],
+  "Utilities": ["sf-reset", "sf-commit", "sf-help"]
+};
+const SCAFFOLD_VERSION = "1.0.0";
+export {
+  COMMAND_CATEGORIES,
+  SCAFFOLD_VERSION
+};
+//# sourceMappingURL=types.js.map

package/dist/cli/commands/scaffold/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/cli/commands/scaffold/types.ts"],"sourcesContent":["/**\n * Scaffold Command Types & Interfaces\n *\n * Type definitions for the scaffold command that generates AI CLI tool commands.\n */\n\n/**\n * Options for the scaffold command\n */\nexport interface ScaffoldOptions {\n  /** Target AI CLI tool (claude, copilot, codex, gemini, opencode, cursor; alias: vscode) */\n  target?: string;\n  /** Install to global location (default) */\n  global?: boolean;\n  /** Install to project .specforge/ */\n  project?: boolean;\n  /** List available commands */\n  list?: boolean;\n  /** Update existing commands to latest version */\n  update?: boolean;\n  /** Force overwrite existing files (configs, instructions) */\n  force?: boolean;\n  /** Show what would be created without writing */\n  dryRun?: boolean;\n  /** Preview a specific command content (interactive if no command specified) */\n  preview?: string | boolean;\n  /** Show diff for outdated commands */\n  diff?: boolean;\n  /** Scaffold MCP config files (.mcp.json, .codex/config.toml, etc.) */\n  configs?: boolean;\n  /** Scaffold instruction files (CLAUDE.md, GEMINI.md, AGENTS.md, etc.) */\n  instructions?: boolean;\n  /** Scaffold AI agents instead of commands */\n  agents?: boolean;\n  /** Scaffold skills instead of commands */\n  skills?: boolean;\n  /** Scaffold slash commands (explicit subset selector) */\n  commands?: boolean;\n  /** Filter agents by category */\n  category?: string;\n}\n\n/**\n * Supported AI CLI targets\n *\n * Note: `vscode` is a string-level alias for `cursor` (resolved at command entry),\n * not a separate target — VS Code with Copilot reads the same `.mcp.json` Cursor reads.\n */\nexport type ScaffoldTarget = 'claude' | 'copilot' | 'codex' | 'gemini' | 'opencode' | 'cursor';\n\n/**\n * Command format for a target\n */\nexport type CommandFormat = 'markdown' | 'toml' | null;\n\n/**\n * Configuration for a target AI CLI tool\n */\nexport interface TargetConfig {\n  /** Display name of the AI CLI tool */\n  name: string;\n  /** Detection path — directory checked to determine if CLI is installed */\n  detectionPath: () => string;\n  /** Function to get global command installation path */\n  globalCommandPath?: () => string;\n  /** Function to get project command installation path */\n  projectCommandPath?: () => string;\n  /** Function to get global skill installation path */\n  globalSkillPath?: () => string;\n  /** Function to get project skill installation path */\n  projectSkillPath?: () => string;\n  /** Function to get global agent installation path */\n  globalAgentPath?: () => string;\n  /** Function to get project agent installation path */\n  projectAgentPath?: () => string;\n  /** File extension for command files */\n  commandExtension: string;\n  /** File extension for skill files */\n  skillExtension: string;\n  /** File extension for agent files */\n  agentExtension: string;\n  /** Whether commands use YAML frontmatter */\n  commandFrontmatter: boolean;\n  /** Whether skills use YAML frontmatter (agentskills.io) */\n  skillFrontmatter: boolean;\n  /** Whether agents use YAML frontmatter */\n  agentFrontmatter: boolean;\n  /** Whether the target supports slash commands */\n  supportsCommands: boolean;\n  /** Whether the target supports skills */\n  supportsSkills: boolean;\n  /** Whether the target supports AI agents */\n  supportsAgents: boolean;\n  /** Command format (markdown, toml, or null if unsupported) */\n  commandFormat: CommandFormat;\n  /** Argument syntax for commands (e.g., '$ARGUMENTS', '{{args}}') */\n  argSyntax: string | null;\n  /** Instruction file name for this CLI (e.g., 'CLAUDE.md', 'GEMINI.md'); null = use AGENTS.md fallback */\n  instructionFile?: string | null;\n  /** Instruction file path (relative, e.g., '.github/copilot-instructions.md'); null = use AGENTS.md fallback */\n  instructionFilePath?: string | null;\n  /** MCP config file path */\n  mcpConfigPath?: string;\n  /** MCP config format */\n  mcpConfigFormat?: 'claude-json' | 'gemini-json' | 'codex-toml' | 'opencode-json';\n  /** Usage hint for after scaffolding */\n  usageHint?: string;\n  /** Usage hint for agents after scaffolding */\n  agentUsageHint?: string;\n\n  // Legacy compatibility — kept for backward compat with existing scaffold code\n  /** @deprecated Use globalCommandPath */\n  globalPath: () => string;\n  /** @deprecated Use projectCommandPath */\n  projectPath: () => string;\n  /** @deprecated Use commandExtension */\n  fileExtension: string;\n  /** @deprecated Use commandFrontmatter */\n  needsFrontmatter: boolean;\n}\n\n/**\n * Map of all target configurations\n */\nexport type TargetConfigMap = Record<ScaffoldTarget, TargetConfig>;\n\n/**\n * Command template definition\n */\nexport interface CommandTemplate {\n  /** Command name (e.g., 'sf-init') */\n  name: string;\n  /** Short description for command list */\n  description: string;\n  /** Argument hint for frontmatter (e.g., '[specification-id]') */\n  argumentHint?: string;\n  /** Full markdown content of the command */\n  content: string;\n  /** Command category for grouping */\n  category: CommandCategory;\n}\n\nexport type CommandCategory =\n  | 'Setup'\n  | 'Status'\n  | 'Review'\n  | 'Utilities';\n\n/**\n * Scaffolding result statistics\n */\nexport interface ScaffoldResult {\n  /** Number of files created */\n  created: number;\n  /** Number of files updated */\n  updated: number;\n  /** Number of files skipped (identical) */\n  skipped: number;\n  /** Number of files outdated (skipped but different) */\n  outdated: number;\n  /** Target path where files were written */\n  targetPath: string;\n}\n\n/**\n * File comparison status\n */\nexport type FileStatus = 'new' | 'identical' | 'outdated';\n\n/**\n * File comparison result\n */\nexport interface FileComparison {\n  /** Status of the file */\n  status: FileStatus;\n  /** Existing content (if file exists) */\n  existingContent?: string;\n  /** New content to write */\n  newContent: string;\n}\n\nexport const COMMAND_CATEGORIES: Record<CommandCategory, string[]> = {\n  'Setup': ['sf-init', 'sf-context'],\n  'Status': ['sf-status', 'sf-analyze-blockers'],\n  'Review': ['sf-search'],\n  'Utilities': ['sf-reset', 'sf-commit', 'sf-help'],\n};\n\n/**\n * Version string for generated commands\n */\nexport const SCAFFOLD_VERSION = '1.0.0';\n"],"mappings":"AAqLO,MAAM,qBAAwD;AAAA,EACnE,SAAS,CAAC,WAAW,YAAY;AAAA,EACjC,UAAU,CAAC,aAAa,qBAAqB;AAAA,EAC7C,UAAU,CAAC,WAAW;AAAA,EACtB,aAAa,CAAC,YAAY,aAAa,SAAS;AAClD;AAKO,MAAM,mBAAmB;","names":[]}

package/dist/cli/commands/scaffold/utils.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Scaffold Utility Functions
+ *
+ * Utility functions for file operations and content generation.
+ */
+import type { CommandTemplate, ScaffoldTarget, FileComparison } from './types.js';
+import type { AgentTemplate } from './agent-types.js';
+/**
+ * Detect which AI CLI tools are installed by checking their detection paths
+ */
+export declare function detectInstalledTools(): ScaffoldTarget[];
+/**
+ * Generate command content for a target format
+ */
+export declare function generateCommandContent(template: CommandTemplate, needsFrontmatter: boolean, target: string): string;
+/**
+ * Generate agent content for a target format.
+ *
+ * File layout (all targets):
+ *   1. YAML frontmatter (if the target supports it)
+ *   2. `<!-- {short-name} SpecForge {cli-version} -->` comment
+ *   3. Agent body content
+ *
+ * The version comment must come AFTER the frontmatter — Claude Code (and
+ * stricter Markdown parsers) only recognize frontmatter when the very first
+ * line of the file is `---`. A leading comment makes the file look like
+ * plain Markdown with no frontmatter, breaking agent registration.
+ */
+export declare function generateAgentContent(template: AgentTemplate, needsFrontmatter: boolean, target?: ScaffoldTarget): string;
+/**
+ * Ensure directory exists
+ */
+export declare function ensureDirectory(dirPath: string): void;
+/**
+ * Check if file exists
+ */
+export declare function fileExists(filePath: string): boolean;
+/**
+ * Write content to file
+ */
+export declare function writeFile(filePath: string, content: string): void;
+/**
+ * Get command filename
+ */
+export declare function getCommandFilename(commandName: string, extension: string): string;
+/**
+ * Get agent filename for a target
+ */
+export declare function getAgentFilename(name: string, target?: ScaffoldTarget): string;
+/**
+ * Get skill directory name (agentskills.io uses SKILL.md inside named directory)
+ */
+export declare function getSkillDirName(name: string): string;
+/**
+ * Read file content
+ */
+export declare function readFile(filePath: string): string | null;
+/**
+ * Compare existing and new content
+ */
+export declare function compareFiles(filePath: string, newContent: string): FileComparison;
+/**
+ * Generate a simple unified diff between two strings
+ */
+export declare function generateDiff(oldContent: string, newContent: string, filename: string): string;
+/**
+ * Options for MCP config generation
+ */
+export interface GenerateMcpConfigOptions {
+    /** When set, bake this API key into the env block instead of using a placeholder */
+    apiKey?: string;
+}
+/**
+ * Generate MCP config content for a specific target.
+ *
+ * When `options.apiKey` is provided, the key is inlined in the `env` block
+ * (matches the legacy `saveMcpConfig()` behavior for Claude). Otherwise a
+ * placeholder is emitted so the agent reads `SPECFORGE_API_KEY` from its env.
+ */
+export declare function generateMcpConfig(target: ScaffoldTarget, options?: GenerateMcpConfigOptions): string;
+/**
+ * Generate AGENTS.md content (universal instruction file)
+ */
+export declare function generateAgentsmd(): string;
+/**
+ * Generate per-target instruction file content
+ */
+export declare function generateInstructionFileContent(target: ScaffoldTarget): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/cli/commands/scaffold/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/scaffold/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,cAAc,EAAc,MAAM,YAAY,CAAC;AAC9F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AA+DtD;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,EAAE,CAWvD;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,eAAe,EACzB,gBAAgB,EAAE,OAAO,EACzB,MAAM,EAAE,MAAM,GACb,MAAM,CAqCR;AAgDD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,aAAa,EACvB,gBAAgB,EAAE,OAAO,EACzB,MAAM,CAAC,EAAE,cAAc,GACtB,MAAM,CAoCR;AAkED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAIrD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAEjE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,MAAM,CAER;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,MAAM,CAK9E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUxD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc,CAgBjF;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAmC7F;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,MAAM,CA0DpG;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAgCzC;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CA0B7E"}

package/dist/cli/commands/scaffold/utils.js

@@ -0,0 +1,401 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { TARGETS } from "./targets.js";
+import { SCAFFOLD_VERSION } from "./types.js";
+import { CHANNEL } from "../../../channel.js";
+function getCliPackageName() {
+  return CHANNEL.packageName;
+}
+let cachedCliVersion = null;
+function getCliVersion() {
+  if (cachedCliVersion) return cachedCliVersion;
+  try {
+    const pkg = readCliPackageJson();
+    const version = typeof pkg.version === "string" ? pkg.version : "";
+    if (version) {
+      cachedCliVersion = version;
+      return version;
+    }
+  } catch {
+  }
+  cachedCliVersion = SCAFFOLD_VERSION;
+  return cachedCliVersion;
+}
+function readCliPackageJson() {
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = path.dirname(__filename);
+  const packageRoot = path.resolve(__dirname, "..", "..", "..", "..");
+  return JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf-8"));
+}
+function formatAgentVersionComment(agentName) {
+  const shortName = agentName.startsWith("sfag-") ? agentName.slice("sfag-".length) : agentName;
+  return `<!-- ${shortName} SpecForge ${getCliVersion()} -->`;
+}
+function detectInstalledTools() {
+  const installed = [];
+  for (const [target, config] of Object.entries(TARGETS)) {
+    const detectionDir = config.detectionPath();
+    if (fs.existsSync(detectionDir)) {
+      installed.push(target);
+    }
+  }
+  return installed;
+}
+function generateCommandContent(template, needsFrontmatter, target) {
+  const config = TARGETS[target];
+  if (config?.commandFormat === "toml") {
+    return generateTomlCommandContent(template, target);
+  }
+  let content = "";
+  content += `<!-- SpecForge v${SCAFFOLD_VERSION} -->
+`;
+  if (needsFrontmatter) {
+    content += "---\n";
+    if (template.argumentHint) {
+      content += `argument-hint: ${template.argumentHint}
+`;
+    }
+    content += `description: ${template.description}
+`;
+    content += "---\n\n";
+  }
+  let body = template.content;
+  if (config?.argSyntax && config.argSyntax !== "$ARGUMENTS") {
+    body = body.replace(/\$ARGUMENTS/g, config.argSyntax);
+  }
+  content += body;
+  content = content.replace(/\{TARGET\}/g, target);
+  return content;
+}
+function generateTomlCommandContent(template, target) {
+  let body = template.content;
+  body = body.replace(/\$ARGUMENTS/g, "{{args}}");
+  body = body.replace(/\{TARGET\}/g, target);
+  const escapedBody = body.replace(/"""/g, '\\"\\"\\"');
+  let content = `# SpecForge v${SCAFFOLD_VERSION}
+`;
+  content += `description = "${escapeTomlString(template.description)}"
+`;
+  content += `prompt = """
+${escapedBody}
+"""
+`;
+  return content;
+}
+function escapeTomlString(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function escapeYaml(value) {
+  if (value.includes(":") || value.includes("#") || value.includes("\n") || value.includes('"') || value.includes("'") || value.startsWith(" ") || value.endsWith(" ")) {
+    if (value.includes("\n")) {
+      const lines = value.split("\n").map((line) => `  ${line}`).join("\n");
+      return `|
+${lines}`;
+    }
+    return `"${value.replace(/"/g, '\\"')}"`;
+  }
+  return value;
+}
+function generateAgentContent(template, needsFrontmatter, target) {
+  const config = target ? TARGETS[target] : void 0;
+  if (target === "copilot") {
+    return generateCopilotAgentContent(template);
+  }
+  if (target === "gemini") {
+    return generateGeminiAgentContent(template);
+  }
+  if (target === "opencode") {
+    return generateOpenCodeAgentContent(template);
+  }
+  let content = "";
+  if (needsFrontmatter || (config?.agentFrontmatter ?? needsFrontmatter)) {
+    content += "---\n";
+    content += `name: ${template.name}
+`;
+    content += `description: ${escapeYaml(template.triggerDescription)}
+`;
+    content += `model: ${template.model}
+`;
+    content += `color: ${template.color}
+`;
+    if (template.memory) {
+      content += `memory: ${template.memory}
+`;
+    }
+    content += "---\n\n";
+  }
+  content += `${formatAgentVersionComment(template.name)}
+
+`;
+  content += template.content;
+  return content;
+}
+const MODEL_MAP = {
+  claude: { opus: "opus", sonnet: "sonnet", haiku: "haiku" },
+  copilot: { opus: "", sonnet: "", haiku: "" },
+  // Copilot doesn't support model selection
+  gemini: { opus: "gemini-2.5-pro", sonnet: "gemini-2.5-flash", haiku: "gemini-2.0-flash-lite" },
+  codex: { opus: "", sonnet: "", haiku: "" },
+  // Codex uses TOML roles
+  opencode: {
+    opus: "anthropic/claude-opus-4-20250514",
+    sonnet: "anthropic/claude-sonnet-4-20250514",
+    haiku: "anthropic/claude-haiku-4-20250514"
+  }
+};
+function generateCopilotAgentContent(template) {
+  let content = "---\n";
+  content += `name: ${template.name}
+`;
+  content += `description: ${escapeYaml(template.triggerDescription)}
+`;
+  content += "---\n\n";
+  content += `${formatAgentVersionComment(template.name)}
+
+`;
+  content += template.content;
+  return content;
+}
+function generateGeminiAgentContent(template) {
+  const model = MODEL_MAP.gemini[template.model] || "gemini-2.5-flash";
+  let content = "---\n";
+  content += `name: ${template.name}
+`;
+  content += `description: ${escapeYaml(template.triggerDescription)}
+`;
+  content += `model: ${model}
+`;
+  content += `temperature: 0.2
+`;
+  content += `max_turns: 15
+`;
+  content += "---\n\n";
+  content += `${formatAgentVersionComment(template.name)}
+
+`;
+  content += template.content;
+  return content;
+}
+function generateOpenCodeAgentContent(template) {
+  const model = MODEL_MAP.opencode[template.model] || "anthropic/claude-sonnet-4-20250514";
+  let content = "---\n";
+  content += `description: ${escapeYaml(template.triggerDescription)}
+`;
+  content += `mode: subagent
+`;
+  content += `model: ${model}
+`;
+  content += `steps: 50
+`;
+  content += "---\n\n";
+  content += `${formatAgentVersionComment(template.name)}
+
+`;
+  content += template.content;
+  return content;
+}
+function ensureDirectory(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+function fileExists(filePath) {
+  return fs.existsSync(filePath);
+}
+function writeFile(filePath, content) {
+  fs.writeFileSync(filePath, content, "utf-8");
+}
+function getCommandFilename(commandName, extension) {
+  return `${commandName}${extension}`;
+}
+function getAgentFilename(name, target) {
+  if (target === "copilot") {
+    return `${name}.agent.md`;
+  }
+  return `${name}.md`;
+}
+function getSkillDirName(name) {
+  return name;
+}
+function readFile(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+    const content = fs.readFileSync(filePath, "utf-8");
+    return content ?? null;
+  } catch {
+    return null;
+  }
+}
+function compareFiles(filePath, newContent) {
+  const existingContent = readFile(filePath);
+  if (existingContent === null) {
+    return { status: "new", newContent };
+  }
+  const normalizedExisting = existingContent.replace(/\r\n/g, "\n").trim();
+  const normalizedNew = newContent.replace(/\r\n/g, "\n").trim();
+  if (normalizedExisting === normalizedNew) {
+    return { status: "identical", existingContent, newContent };
+  }
+  return { status: "outdated", existingContent, newContent };
+}
+function generateDiff(oldContent, newContent, filename) {
+  const oldLines = oldContent.split("\n");
+  const newLines = newContent.split("\n");
+  const diff = [];
+  diff.push(`--- a/${filename}`);
+  diff.push(`+++ b/${filename}`);
+  const maxLines = Math.max(oldLines.length, newLines.length);
+  let hasChanges = false;
+  for (let i = 0; i < maxLines; i++) {
+    const oldLine = oldLines[i] ?? "";
+    const newLine = newLines[i] ?? "";
+    if (oldLine !== newLine) {
+      if (!hasChanges) {
+        hasChanges = true;
+        diff.push(`@@ -${i + 1} +${i + 1} @@`);
+      }
+      if (i < oldLines.length) {
+        diff.push(`- ${oldLine}`);
+      }
+      if (i < newLines.length) {
+        diff.push(`+ ${newLine}`);
+      }
+    }
+  }
+  if (!hasChanges) {
+    return "(no differences)";
+  }
+  return diff.join("\n");
+}
+function generateMcpConfig(target, options) {
+  const apiKey = options?.apiKey;
+  const pkg = getCliPackageName();
+  switch (target) {
+    case "claude":
+    case "copilot":
+    case "cursor":
+      return JSON.stringify({
+        mcpServers: {
+          specforge: {
+            command: "npx",
+            args: ["-y", pkg],
+            env: { SPECFORGE_API_KEY: apiKey ?? "${SPECFORGE_API_KEY}" }
+          }
+        }
+      }, null, 2) + "\n";
+    case "gemini":
+      return JSON.stringify({
+        mcpServers: {
+          specforge: {
+            command: "npx",
+            args: ["-y", pkg],
+            env: { SPECFORGE_API_KEY: apiKey ?? "$SPECFORGE_API_KEY" }
+          }
+        }
+      }, null, 2) + "\n";
+    case "codex":
+      return [
+        "[mcp_servers.specforge]",
+        'command = "npx"',
+        `args = ["-y", "${pkg}"]`,
+        "",
+        "[mcp_servers.specforge.env]",
+        apiKey ? `SPECFORGE_API_KEY = "${apiKey.replace(/"/g, '\\"')}"` : 'SPECFORGE_API_KEY = ""  # Set via environment',
+        ""
+      ].join("\n");
+    case "opencode":
+      return JSON.stringify({
+        mcp: {
+          specforge: {
+            type: "local",
+            command: "npx",
+            args: ["-y", pkg],
+            env: { SPECFORGE_API_KEY: apiKey ?? "{env:SPECFORGE_API_KEY}" }
+          }
+        }
+      }, null, 2) + "\n";
+    default:
+      return "";
+  }
+}
+function generateAgentsmd() {
+  return `# SpecForge Project Instructions
+
+This project uses [SpecForge](https://specforge.com.br) for specification-driven development.
+
+## MCP Server
+
+This project has a SpecForge MCP server configured. Use SpecForge MCP tools
+for all specification, epic, ticket, and lifecycle operations.
+
+## Lifecycle
+
+SpecForge follows a 3-phase lifecycle:
+
+1. **Planning** \u2014 Create specifications, epics, tickets, and dependency graphs
+2. **Implementation** \u2014 Work through tickets using the work session lifecycle
+3. **Review** \u2014 Run review gates, address findings, complete specification
+
+## Key MCP Tools
+
+- \`get\` / \`list\` / \`search\` \u2014 Query specifications, epics, tickets
+- \`start_work_session\` / \`action_work_session\` / \`complete_work_session\` \u2014 Ticket implementation lifecycle
+- \`get_next_actionable_tickets\` \u2014 Find ready tickets (all dependencies satisfied)
+- \`get_critical_path\` / \`get_dependency_tree\` \u2014 Analyze ticket dependencies
+
+## Conventions
+
+- Follow the implementation guide provided by \`start_work_session\`
+- Report progress atomically via \`action_work_session\` (steps, AC, files, tests)
+- Never self-assess progress \u2014 it's computed server-side
+- Complete tickets via \`complete_work_session\` \u2014 quality gates are enforced
+`;
+}
+function generateInstructionFileContent(target) {
+  const config = TARGETS[target];
+  return `# SpecForge \u2014 ${config.name} Instructions
+
+This project uses [SpecForge](https://specforge.com.br) for specification-driven development.
+
+## MCP Server
+
+A SpecForge MCP server is configured for this project. Use SpecForge MCP tools
+for all specification, epic, ticket, and lifecycle operations.
+
+## Quick Start
+
+1. Use \`get_specification\` to view the current specification
+2. Use \`get_next_actionable_tickets\` to find tickets ready for implementation
+3. Use \`start_work_session\` to begin working on a ticket
+4. Track progress with \`action_work_session\`
+5. Complete work with \`complete_work_session\`
+
+## Conventions
+
+- Follow the implementation guide provided by \`start_work_session\`
+- Report progress atomically via \`action_work_session\`
+- Never self-assess progress \u2014 it's computed server-side
+- Complete tickets via \`complete_work_session\` \u2014 quality gates are enforced
+`;
+}
+export {
+  compareFiles,
+  detectInstalledTools,
+  ensureDirectory,
+  fileExists,
+  generateAgentContent,
+  generateAgentsmd,
+  generateCommandContent,
+  generateDiff,
+  generateInstructionFileContent,
+  generateMcpConfig,
+  getAgentFilename,
+  getCommandFilename,
+  getSkillDirName,
+  readFile,
+  writeFile
+};
+//# sourceMappingURL=utils.js.map

package/dist/cli/commands/scaffold/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/cli/commands/scaffold/utils.ts"],"sourcesContent":["/**\n * Scaffold Utility Functions\n *\n * Utility functions for file operations and content generation.\n */\n\nimport fs from 'fs';\nimport path from 'path';\nimport { fileURLToPath } from 'url';\nimport type { CommandTemplate, ScaffoldTarget, FileComparison, FileStatus } from './types.js';\nimport type { AgentTemplate } from './agent-types.js';\nimport { TARGETS } from './targets.js';\nimport { SCAFFOLD_VERSION } from './types.js';\nimport { CHANNEL } from '../../../channel.js';\n\n/**\n * The CLI's published package name for the active channel (M9.6c).\n *\n * Flows from `CHANNEL.packageName` — the build (`channel-defines.ts`)\n * substitutes the per-channel published name, so the `.mcp.json` scaffolded\n * into a user project always points at the binary that produced it (stable vs\n * canary). No package.json read, no hardcoded fallback.\n */\nfunction getCliPackageName(): string {\n  return CHANNEL.packageName;\n}\n\n/**\n * Read the CLI's own version from its package.json. Used to stamp scaffolded\n * agent files with the version of the CLI that produced them, so users can\n * tell at a glance whether their agents are stale relative to a newer CLI.\n *\n * Falls back to SCAFFOLD_VERSION if package.json can't be read.\n */\nlet cachedCliVersion: string | null = null;\nfunction getCliVersion(): string {\n  if (cachedCliVersion) return cachedCliVersion;\n  try {\n    const pkg = readCliPackageJson();\n    const version = typeof pkg.version === 'string' ? pkg.version : '';\n    if (version) {\n      cachedCliVersion = version;\n      return version;\n    }\n  } catch {\n    // fall through to default\n  }\n  cachedCliVersion = SCAFFOLD_VERSION;\n  return cachedCliVersion;\n}\n\nfunction readCliPackageJson(): { name?: unknown; version?: unknown } {\n  const __filename = fileURLToPath(import.meta.url);\n  const __dirname = path.dirname(__filename);\n  // dist/cli/commands/scaffold/utils.js → dist/cli/commands/scaffold → dist/cli/commands → dist/cli → dist → packageRoot\n  // src/cli/commands/scaffold/utils.ts follows the same shape.\n  const packageRoot = path.resolve(__dirname, '..', '..', '..', '..');\n  return JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8'));\n}\n\n/**\n * Build the version comment stamped on every scaffolded agent file:\n *   <!-- {short-name} SpecForge {cli-version} -->\n *\n * `short-name` strips the `sfag-` prefix (e.g. `sfag-spec-creator` →\n * `spec-creator`) so the comment reads as the agent's role rather than its\n * convention-prefixed identifier.\n */\nfunction formatAgentVersionComment(agentName: string): string {\n  const shortName = agentName.startsWith('sfag-') ? agentName.slice('sfag-'.length) : agentName;\n  return `<!-- ${shortName} SpecForge ${getCliVersion()} -->`;\n}\n\n/**\n * Detect which AI CLI tools are installed by checking their detection paths\n */\nexport function detectInstalledTools(): ScaffoldTarget[] {\n  const installed: ScaffoldTarget[] = [];\n\n  for (const [target, config] of Object.entries(TARGETS)) {\n    const detectionDir = config.detectionPath();\n    if (fs.existsSync(detectionDir)) {\n      installed.push(target as ScaffoldTarget);\n    }\n  }\n\n  return installed;\n}\n\n/**\n * Generate command content for a target format\n */\nexport function generateCommandContent(\n  template: CommandTemplate,\n  needsFrontmatter: boolean,\n  target: string\n): string {\n  const config = TARGETS[target as ScaffoldTarget];\n\n  // Gemini uses TOML format for commands\n  if (config?.commandFormat === 'toml') {\n    return generateTomlCommandContent(template, target);\n  }\n\n  let content = '';\n\n  // Add version comment\n  content += `<!-- SpecForge v${SCAFFOLD_VERSION} -->\\n`;\n\n  // Add YAML frontmatter if needed (Claude Code)\n  if (needsFrontmatter) {\n    content += '---\\n';\n    if (template.argumentHint) {\n      content += `argument-hint: ${template.argumentHint}\\n`;\n    }\n    content += `description: ${template.description}\\n`;\n    content += '---\\n\\n';\n  }\n\n  // Add main content\n  let body = template.content;\n\n  // Transform argument syntax for target\n  if (config?.argSyntax && config.argSyntax !== '$ARGUMENTS') {\n    body = body.replace(/\\$ARGUMENTS/g, config.argSyntax);\n  }\n\n  content += body;\n\n  // Replace any target-specific placeholders\n  content = content.replace(/\\{TARGET\\}/g, target);\n\n  return content;\n}\n\n/**\n * Generate TOML command content for Gemini CLI\n */\nfunction generateTomlCommandContent(template: CommandTemplate, target: string): string {\n  let body = template.content;\n\n  // Transform argument syntax for Gemini\n  body = body.replace(/\\$ARGUMENTS/g, '{{args}}');\n  body = body.replace(/\\{TARGET\\}/g, target);\n\n  // Escape triple quotes in content\n  const escapedBody = body.replace(/\"\"\"/g, '\\\\\"\\\\\"\\\\\"');\n\n  let content = `# SpecForge v${SCAFFOLD_VERSION}\\n`;\n  content += `description = \"${escapeTomlString(template.description)}\"\\n`;\n  content += `prompt = \"\"\"\\n${escapedBody}\\n\"\"\"\\n`;\n\n  return content;\n}\n\n/**\n * Escape a string for TOML inline value\n */\nfunction escapeTomlString(value: string): string {\n  return value.replace(/\\\\/g, '\\\\\\\\').replace(/\"/g, '\\\\\"');\n}\n\n/**\n * Escape YAML string values\n */\nfunction escapeYaml(value: string): string {\n  // If value contains special characters, wrap in quotes\n  if (value.includes(':') || value.includes('#') || value.includes('\\n') ||\n      value.includes('\"') || value.includes(\"'\") || value.startsWith(' ') ||\n      value.endsWith(' ')) {\n    // Use literal block scalar for multiline content\n    if (value.includes('\\n')) {\n      const lines = value.split('\\n').map(line => `  ${line}`).join('\\n');\n      return `|\\n${lines}`;\n    }\n    // Use double quotes for single line, escaping internal quotes\n    return `\"${value.replace(/\"/g, '\\\\\"')}\"`;\n  }\n  return value;\n}\n\n/**\n * Generate agent content for a target format.\n *\n * File layout (all targets):\n *   1. YAML frontmatter (if the target supports it)\n *   2. `<!-- {short-name} SpecForge {cli-version} -->` comment\n *   3. Agent body content\n *\n * The version comment must come AFTER the frontmatter — Claude Code (and\n * stricter Markdown parsers) only recognize frontmatter when the very first\n * line of the file is `---`. A leading comment makes the file look like\n * plain Markdown with no frontmatter, breaking agent registration.\n */\nexport function generateAgentContent(\n  template: AgentTemplate,\n  needsFrontmatter: boolean,\n  target?: ScaffoldTarget\n): string {\n  const config = target ? TARGETS[target] : undefined;\n\n  // For Copilot, use .agent.md frontmatter format (no color)\n  if (target === 'copilot') {\n    return generateCopilotAgentContent(template);\n  }\n\n  // For Gemini, include temperature and max_turns\n  if (target === 'gemini') {\n    return generateGeminiAgentContent(template);\n  }\n\n  // For OpenCode, use provider/model-id format\n  if (target === 'opencode') {\n    return generateOpenCodeAgentContent(template);\n  }\n\n  // Default: Claude Code format (or generic)\n  let content = '';\n\n  if (needsFrontmatter || (config?.agentFrontmatter ?? needsFrontmatter)) {\n    content += '---\\n';\n    content += `name: ${template.name}\\n`;\n    content += `description: ${escapeYaml(template.triggerDescription)}\\n`;\n    content += `model: ${template.model}\\n`;\n    content += `color: ${template.color}\\n`;\n    if (template.memory) {\n      content += `memory: ${template.memory}\\n`;\n    }\n    content += '---\\n\\n';\n  }\n\n  content += `${formatAgentVersionComment(template.name)}\\n\\n`;\n  content += template.content;\n  return content;\n}\n\n/**\n * Model tier mapping for each target\n */\nconst MODEL_MAP: Record<string, Record<string, string>> = {\n  claude: { opus: 'opus', sonnet: 'sonnet', haiku: 'haiku' },\n  copilot: { opus: '', sonnet: '', haiku: '' }, // Copilot doesn't support model selection\n  gemini: { opus: 'gemini-2.5-pro', sonnet: 'gemini-2.5-flash', haiku: 'gemini-2.0-flash-lite' },\n  codex: { opus: '', sonnet: '', haiku: '' }, // Codex uses TOML roles\n  opencode: {\n    opus: 'anthropic/claude-opus-4-20250514',\n    sonnet: 'anthropic/claude-sonnet-4-20250514',\n    haiku: 'anthropic/claude-haiku-4-20250514',\n  },\n};\n\n/**\n * Generate Copilot CLI agent content (.agent.md format)\n */\nfunction generateCopilotAgentContent(template: AgentTemplate): string {\n  let content = '---\\n';\n  content += `name: ${template.name}\\n`;\n  content += `description: ${escapeYaml(template.triggerDescription)}\\n`;\n  // No model field — Copilot doesn't support it in coding agent\n  content += '---\\n\\n';\n  content += `${formatAgentVersionComment(template.name)}\\n\\n`;\n  content += template.content;\n  return content;\n}\n\n/**\n * Generate Gemini CLI agent content\n */\nfunction generateGeminiAgentContent(template: AgentTemplate): string {\n  const model = MODEL_MAP.gemini[template.model] || 'gemini-2.5-flash';\n\n  let content = '---\\n';\n  content += `name: ${template.name}\\n`;\n  content += `description: ${escapeYaml(template.triggerDescription)}\\n`;\n  content += `model: ${model}\\n`;\n  content += `temperature: 0.2\\n`;\n  content += `max_turns: 15\\n`;\n  content += '---\\n\\n';\n  content += `${formatAgentVersionComment(template.name)}\\n\\n`;\n  content += template.content;\n  return content;\n}\n\n/**\n * Generate OpenCode agent content\n */\nfunction generateOpenCodeAgentContent(template: AgentTemplate): string {\n  const model = MODEL_MAP.opencode[template.model] || 'anthropic/claude-sonnet-4-20250514';\n\n  let content = '---\\n';\n  content += `description: ${escapeYaml(template.triggerDescription)}\\n`;\n  content += `mode: subagent\\n`;\n  content += `model: ${model}\\n`;\n  content += `steps: 50\\n`;\n  content += '---\\n\\n';\n  content += `${formatAgentVersionComment(template.name)}\\n\\n`;\n  content += template.content;\n  return content;\n}\n\n/**\n * Ensure directory exists\n */\nexport function ensureDirectory(dirPath: string): void {\n  if (!fs.existsSync(dirPath)) {\n    fs.mkdirSync(dirPath, { recursive: true });\n  }\n}\n\n/**\n * Check if file exists\n */\nexport function fileExists(filePath: string): boolean {\n  return fs.existsSync(filePath);\n}\n\n/**\n * Write content to file\n */\nexport function writeFile(filePath: string, content: string): void {\n  fs.writeFileSync(filePath, content, 'utf-8');\n}\n\n/**\n * Get command filename\n */\nexport function getCommandFilename(\n  commandName: string,\n  extension: string\n): string {\n  return `${commandName}${extension}`;\n}\n\n/**\n * Get agent filename for a target\n */\nexport function getAgentFilename(name: string, target?: ScaffoldTarget): string {\n  if (target === 'copilot') {\n    return `${name}.agent.md`;\n  }\n  return `${name}.md`;\n}\n\n/**\n * Get skill directory name (agentskills.io uses SKILL.md inside named directory)\n */\nexport function getSkillDirName(name: string): string {\n  return name;\n}\n\n/**\n * Read file content\n */\nexport function readFile(filePath: string): string | null {\n  try {\n    if (!fs.existsSync(filePath)) {\n      return null;\n    }\n    const content = fs.readFileSync(filePath, 'utf-8');\n    return content ?? null; // Handle undefined from mocks\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Compare existing and new content\n */\nexport function compareFiles(filePath: string, newContent: string): FileComparison {\n  const existingContent = readFile(filePath);\n\n  if (existingContent === null) {\n    return { status: 'new', newContent };\n  }\n\n  // Normalize line endings for comparison\n  const normalizedExisting = existingContent.replace(/\\r\\n/g, '\\n').trim();\n  const normalizedNew = newContent.replace(/\\r\\n/g, '\\n').trim();\n\n  if (normalizedExisting === normalizedNew) {\n    return { status: 'identical', existingContent, newContent };\n  }\n\n  return { status: 'outdated', existingContent, newContent };\n}\n\n/**\n * Generate a simple unified diff between two strings\n */\nexport function generateDiff(oldContent: string, newContent: string, filename: string): string {\n  const oldLines = oldContent.split('\\n');\n  const newLines = newContent.split('\\n');\n\n  const diff: string[] = [];\n  diff.push(`--- a/${filename}`);\n  diff.push(`+++ b/${filename}`);\n\n  // Simple line-by-line diff (not a real unified diff, but good enough for preview)\n  const maxLines = Math.max(oldLines.length, newLines.length);\n  let hasChanges = false;\n\n  for (let i = 0; i < maxLines; i++) {\n    const oldLine = oldLines[i] ?? '';\n    const newLine = newLines[i] ?? '';\n\n    if (oldLine !== newLine) {\n      if (!hasChanges) {\n        hasChanges = true;\n        diff.push(`@@ -${i + 1} +${i + 1} @@`);\n      }\n      if (i < oldLines.length) {\n        diff.push(`- ${oldLine}`);\n      }\n      if (i < newLines.length) {\n        diff.push(`+ ${newLine}`);\n      }\n    }\n  }\n\n  if (!hasChanges) {\n    return '(no differences)';\n  }\n\n  return diff.join('\\n');\n}\n\n/**\n * Options for MCP config generation\n */\nexport interface GenerateMcpConfigOptions {\n  /** When set, bake this API key into the env block instead of using a placeholder */\n  apiKey?: string;\n}\n\n/**\n * Generate MCP config content for a specific target.\n *\n * When `options.apiKey` is provided, the key is inlined in the `env` block\n * (matches the legacy `saveMcpConfig()` behavior for Claude). Otherwise a\n * placeholder is emitted so the agent reads `SPECFORGE_API_KEY` from its env.\n */\nexport function generateMcpConfig(target: ScaffoldTarget, options?: GenerateMcpConfigOptions): string {\n  const apiKey = options?.apiKey;\n  const pkg = getCliPackageName();\n\n  switch (target) {\n    case 'claude':\n    case 'copilot':\n    case 'cursor':\n      // Shared .mcp.json format — Claude Code, Copilot, Cursor, VS Code all read it\n      return JSON.stringify({\n        mcpServers: {\n          specforge: {\n            command: 'npx',\n            args: ['-y', pkg],\n            env: { SPECFORGE_API_KEY: apiKey ?? '${SPECFORGE_API_KEY}' },\n          },\n        },\n      }, null, 2) + '\\n';\n\n    case 'gemini':\n      return JSON.stringify({\n        mcpServers: {\n          specforge: {\n            command: 'npx',\n            args: ['-y', pkg],\n            env: { SPECFORGE_API_KEY: apiKey ?? '$SPECFORGE_API_KEY' },\n          },\n        },\n      }, null, 2) + '\\n';\n\n    case 'codex':\n      return [\n        '[mcp_servers.specforge]',\n        'command = \"npx\"',\n        `args = [\"-y\", \"${pkg}\"]`,\n        '',\n        '[mcp_servers.specforge.env]',\n        apiKey\n          ? `SPECFORGE_API_KEY = \"${apiKey.replace(/\"/g, '\\\\\"')}\"`\n          : 'SPECFORGE_API_KEY = \"\"  # Set via environment',\n        '',\n      ].join('\\n');\n\n    case 'opencode':\n      return JSON.stringify({\n        mcp: {\n          specforge: {\n            type: 'local',\n            command: 'npx',\n            args: ['-y', pkg],\n            env: { SPECFORGE_API_KEY: apiKey ?? '{env:SPECFORGE_API_KEY}' },\n          },\n        },\n      }, null, 2) + '\\n';\n\n    default:\n      return '';\n  }\n}\n\n/**\n * Generate AGENTS.md content (universal instruction file)\n */\nexport function generateAgentsmd(): string {\n  return `# SpecForge Project Instructions\n\nThis project uses [SpecForge](https://specforge.com.br) for specification-driven development.\n\n## MCP Server\n\nThis project has a SpecForge MCP server configured. Use SpecForge MCP tools\nfor all specification, epic, ticket, and lifecycle operations.\n\n## Lifecycle\n\nSpecForge follows a 3-phase lifecycle:\n\n1. **Planning** — Create specifications, epics, tickets, and dependency graphs\n2. **Implementation** — Work through tickets using the work session lifecycle\n3. **Review** — Run review gates, address findings, complete specification\n\n## Key MCP Tools\n\n- \\`get\\` / \\`list\\` / \\`search\\` — Query specifications, epics, tickets\n- \\`start_work_session\\` / \\`action_work_session\\` / \\`complete_work_session\\` — Ticket implementation lifecycle\n- \\`get_next_actionable_tickets\\` — Find ready tickets (all dependencies satisfied)\n- \\`get_critical_path\\` / \\`get_dependency_tree\\` — Analyze ticket dependencies\n\n## Conventions\n\n- Follow the implementation guide provided by \\`start_work_session\\`\n- Report progress atomically via \\`action_work_session\\` (steps, AC, files, tests)\n- Never self-assess progress — it's computed server-side\n- Complete tickets via \\`complete_work_session\\` — quality gates are enforced\n`;\n}\n\n/**\n * Generate per-target instruction file content\n */\nexport function generateInstructionFileContent(target: ScaffoldTarget): string {\n  const config = TARGETS[target];\n  return `# SpecForge — ${config.name} Instructions\n\nThis project uses [SpecForge](https://specforge.com.br) for specification-driven development.\n\n## MCP Server\n\nA SpecForge MCP server is configured for this project. Use SpecForge MCP tools\nfor all specification, epic, ticket, and lifecycle operations.\n\n## Quick Start\n\n1. Use \\`get_specification\\` to view the current specification\n2. Use \\`get_next_actionable_tickets\\` to find tickets ready for implementation\n3. Use \\`start_work_session\\` to begin working on a ticket\n4. Track progress with \\`action_work_session\\`\n5. Complete work with \\`complete_work_session\\`\n\n## Conventions\n\n- Follow the implementation guide provided by \\`start_work_session\\`\n- Report progress atomically via \\`action_work_session\\`\n- Never self-assess progress — it's computed server-side\n- Complete tickets via \\`complete_work_session\\` — quality gates are enforced\n`;\n}\n"],"mappings":"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","names":[]}

package/dist/cli/commands/status.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Status Command
+ *
+ * Shows what this terminal is pointed at (project / spec from
+ * `.specforge/config.json`) plus a live implementation report for the active
+ * spec and the next actionable tickets. Uses only canonical tools —
+ * `get_report` (type='implementation') + `get_next_actionable_tickets`.
+ */
+import { Command } from 'commander';
+import { StatusOptions } from './status.types.js';
+/**
+ * Status command action handler
+ */
+export declare function statusAction(options: StatusOptions): Promise<void>;
+/**
+ * Register status command with Commander
+ */
+export declare function registerStatusCommand(program: Command): void;
+//# sourceMappingURL=status.d.ts.map

package/dist/cli/commands/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/status.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,OAAO,EACL,aAAa,EAGd,MAAM,mBAAmB,CAAC;AA0D3B;;GAEG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAoExE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAkB5D"}