@aigne/doc-smith 0.9.10 → 0.9.11-beta

package/utils/workspace.mjs

@@ -0,0 +1,371 @@
+import { existsSync } from "node:fs";
+import { access, readFile, mkdir, writeFile, appendFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { join } from "node:path";
+import { parse as yamlParse, stringify as yamlStringify } from "yaml";
+
+const execAsync = promisify(exec);
+
+/**
+ * Workspace mode constants
+ */
+export const WORKSPACE_MODES = {
+  PROJECT: "project",
+  STANDALONE: "standalone",
+};
+
+/**
+ * Directory structure constants
+ */
+export const AIGNE_DIR = ".aigne";
+export const DOC_SMITH_DIR = ".aigne/doc-smith";
+export const SOURCES_DIR = "sources";
+export const WORKSPACE_SUBDIRS = ["intent", "planning", "docs"];
+
+/**
+ * .gitignore content for doc-smith workspace
+ */
+export const GITIGNORE_CONTENT = `\
+# Ignore sources directory
+sources/
+
+# Ignore temporary files
+.tmp/
+.temp/
+temp/
+`;
+
+/**
+ * Check if path exists
+ * @param {string} path - Path
+ * @returns {Promise<boolean>}
+ */
+export async function pathExists(path) {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if path exists (synchronous version)
+ * @param {string} path - Path
+ * @returns {boolean}
+ */
+export function pathExistsSync(path) {
+  return existsSync(path);
+}
+
+/**
+ * Check if inside a git repository (supports subdirectories)
+ * @param {string} cwd - Working directory
+ * @returns {Promise<boolean>}
+ */
+export async function isGitRepo(cwd = ".") {
+  const result = await gitExec("rev-parse --is-inside-work-tree", cwd);
+  return result.success && result.output === "true";
+}
+
+/**
+ * Execute git command
+ * @param {string} command - git command (without git prefix)
+ * @param {string} cwd - Working directory
+ * @returns {Promise<{success: boolean, output?: string, error?: string}>}
+ */
+export async function gitExec(command, cwd = ".") {
+  try {
+    const { stdout } = await execAsync(`git ${command}`, { cwd });
+    return { success: true, output: stdout.trim() };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Get git repository info (url, branch, commit)
+ * @param {string} cwd - Working directory
+ * @returns {Promise<{ url: string, branch: string, commit: string }>}
+ */
+export async function getGitInfo(cwd = ".") {
+  // Get remote repository URL (prefer origin)
+  let url = "";
+  const urlResult = await gitExec("remote get-url origin", cwd);
+  if (urlResult.success) {
+    url = urlResult.output;
+  } else {
+    // Try to get the first available remote
+    const remotesResult = await gitExec("remote", cwd);
+    if (remotesResult.success && remotesResult.output) {
+      const firstRemote = remotesResult.output.split("\n")[0];
+      const fallbackResult = await gitExec(`remote get-url ${firstRemote}`, cwd);
+      if (fallbackResult.success) {
+        url = fallbackResult.output;
+      }
+    }
+  }
+
+  // Get current branch name
+  let branch = "";
+  const branchResult = await gitExec("branch --show-current", cwd);
+  if (branchResult.success) {
+    branch = branchResult.output;
+  }
+
+  // Get current commit hash (short format)
+  let commit = "";
+  const commitResult = await gitExec("rev-parse --short HEAD", cwd);
+  if (commitResult.success) {
+    commit = commitResult.output;
+  }
+
+  return { url, branch, commit };
+}
+
+/**
+ * Get git repository root directory
+ * @param {string} cwd - Starting directory
+ * @returns {Promise<string | null>}
+ */
+export async function getGitRoot(cwd = ".") {
+  const result = await gitExec("rev-parse --show-toplevel", cwd);
+  if (result.success) {
+    return result.output;
+  }
+  return null;
+}
+
+/**
+ * Add ignore rule to .gitignore (if not exists)
+ * @param {string} gitRoot - Git repository root directory
+ * @param {string} pattern - Pattern to ignore
+ * @returns {Promise<boolean>} Whether addition was successful
+ */
+export async function addToGitignore(gitRoot, pattern) {
+  const gitignorePath = join(gitRoot, ".gitignore");
+
+  try {
+    // Check if .gitignore exists
+    if (await pathExists(gitignorePath)) {
+      // Read existing content, check if pattern already exists
+      const content = await readFile(gitignorePath, "utf8");
+      if (content.includes(pattern)) {
+        return true; // Already exists, no need to add
+      }
+      // Append to end of file (ensure newline)
+      const prefix = content.endsWith("\n") ? "" : "\n";
+      await appendFile(gitignorePath, `${prefix}${pattern}\n`, "utf8");
+    } else {
+      // Create new .gitignore
+      await writeFile(gitignorePath, `${pattern}\n`, "utf8");
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detect workspace mode (synchronous version)
+ * Used for scenarios requiring synchronous judgment at module load time
+ * @returns {{ mode: string, workspaceBase: string }}
+ */
+export function detectWorkspaceModeSync() {
+  const cwd = process.cwd();
+  const projectConfigPath = join(cwd, DOC_SMITH_DIR, "config.yaml");
+
+  if (existsSync(projectConfigPath)) {
+    return {
+      mode: WORKSPACE_MODES.PROJECT,
+      workspaceBase: join(cwd, DOC_SMITH_DIR),
+    };
+  }
+
+  return {
+    mode: WORKSPACE_MODES.STANDALONE,
+    workspaceBase: cwd,
+  };
+}
+
+/**
+ * Detect workspace mode (asynchronous version)
+ * @returns {Promise<{ mode: string, configPath: string, workspacePath: string } | null>}
+ */
+export async function detectWorkspaceMode() {
+  const configInDocSmith = join(DOC_SMITH_DIR, "config.yaml");
+  const configInRoot = "config.yaml";
+
+  if (await pathExists(configInDocSmith)) {
+    return {
+      mode: WORKSPACE_MODES.PROJECT,
+      configPath: configInDocSmith,
+      workspacePath: `./${DOC_SMITH_DIR}`,
+    };
+  }
+
+  if (await pathExists(configInRoot)) {
+    return {
+      mode: WORKSPACE_MODES.STANDALONE,
+      configPath: configInRoot,
+      workspacePath: ".",
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Load and parse config.yaml
+ * @param {string} configPath - Config file path
+ * @returns {Promise<Object | null>}
+ */
+export async function loadConfig(configPath) {
+  try {
+    const content = await readFile(configPath, "utf8");
+    return yamlParse(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Generate config.yaml content
+ * @param {{ mode: string, sources: Array }} options - Configuration options
+ * @returns {string}
+ */
+export function generateConfig(options) {
+  const { mode, sources } = options;
+  return yamlStringify({ mode, sources });
+}
+
+/**
+ * Create directory structure
+ * @param {string} baseDir - Base directory
+ * @param {boolean} includeSources - Whether to create sources directory
+ */
+export async function createDirectoryStructure(baseDir, includeSources = false) {
+  await mkdir(baseDir, { recursive: true });
+
+  for (const dir of WORKSPACE_SUBDIRS) {
+    await mkdir(join(baseDir, dir), { recursive: true });
+  }
+
+  if (includeSources) {
+    await mkdir(join(baseDir, SOURCES_DIR), { recursive: true });
+  }
+}
+
+/**
+ * Initialize project mode workspace
+ * Create .aigne/doc-smith/ directory structure under project root
+ * @returns {Promise<{ mode: string, configPath: string, workspacePath: string }>}
+ */
+export async function initProjectMode() {
+  console.log("\n📂 Initializing doc-smith workspace...\n");
+
+  // Create .aigne/doc-smith directory
+  await mkdir(DOC_SMITH_DIR, { recursive: true });
+
+  // Initialize git in .aigne/doc-smith
+  await gitExec("init", DOC_SMITH_DIR);
+
+  // Create directory structure
+  await createDirectoryStructure(DOC_SMITH_DIR);
+
+  // Create .gitignore
+  await writeFile(join(DOC_SMITH_DIR, ".gitignore"), GITIGNORE_CONTENT, "utf8");
+
+  // Get project git info
+  const gitInfo = await getGitInfo(".");
+
+  // Generate config.yaml (include git info, consistent with git-clone format)
+  const sourceConfig = {
+    type: "local-path",
+    path: "../../",
+  };
+
+  // Add git info at root level (consistent with git-clone format)
+  if (gitInfo.url) sourceConfig.url = gitInfo.url;
+  if (gitInfo.branch) sourceConfig.branch = gitInfo.branch;
+  if (gitInfo.commit) sourceConfig.commit = gitInfo.commit;
+
+  const configContent = generateConfig({
+    mode: WORKSPACE_MODES.PROJECT,
+    sources: [sourceConfig],
+  });
+  await writeFile(join(DOC_SMITH_DIR, "config.yaml"), configContent, "utf8");
+
+  // Create initial commit in doc-smith repo
+  await gitExec("add .", DOC_SMITH_DIR);
+  const commitResult = await gitExec(
+    'commit -m "Initial commit: doc-smith workspace"',
+    DOC_SMITH_DIR,
+  );
+  if (commitResult.success) {
+    console.log(`✅ Created initial commit in ${DOC_SMITH_DIR}`);
+  }
+
+  console.log("✅ Workspace initialized successfully!\n");
+
+  return {
+    mode: WORKSPACE_MODES.PROJECT,
+    configPath: join(DOC_SMITH_DIR, "config.yaml"),
+    workspacePath: `./${DOC_SMITH_DIR}`,
+  };
+}
+
+/**
+ * Initialize standalone mode workspace
+ * Create workspace structure in current directory
+ * @returns {Promise<{ mode: string, configPath: string, workspacePath: string }>}
+ */
+export async function initStandaloneMode() {
+  console.log("\n📂 Initializing doc-smith workspace...\n");
+
+  // Initialize git in current directory
+  await gitExec("init");
+
+  // Create .gitignore
+  await writeFile(".gitignore", GITIGNORE_CONTENT, "utf8");
+
+  // Create directory structure (including sources/)
+  await createDirectoryStructure(".", true);
+
+  // Generate config.yaml (sources empty, to be added during conversation)
+  const configContent = generateConfig({
+    mode: WORKSPACE_MODES.STANDALONE,
+    sources: [],
+  });
+  await writeFile("config.yaml", configContent, "utf8");
+
+  console.log("✅ Workspace initialized successfully!\n");
+
+  return {
+    mode: WORKSPACE_MODES.STANDALONE,
+    configPath: "config.yaml",
+    workspacePath: ".",
+  };
+}
+
+/**
+ * Detect directory state and initialize workspace when needed
+ * @returns {Promise<{ mode: string, configPath: string, workspacePath: string }>}
+ */
+export async function detectAndInitialize() {
+  // Check if already initialized
+  const existing = await detectWorkspaceMode();
+  if (existing) {
+    return existing;
+  }
+
+  // Check if inside git repository (project mode)
+  if (await isGitRepo()) {
+    return await initProjectMode();
+  }
+
+  // Otherwise, initialize as standalone mode
+  return await initStandaloneMode();
+}

package/agents/chat/chat-system.md

@@ -1,38 +0,0 @@
-You are a professional document generation assistant that helps users create, modify, and manage documentation through interactive chat. Your primary role is to understand user requirements and intelligently call upon various specialized skills to complete documentation tasks efficiently.
-
-Core Capabilities:
-- Generate comprehensive documentation from user inputs and specifications
-- Regenerate and refine document details based on feedback
-- Translate and localize documentation content
-- Publish and manage team documentation workflows
-- Provide interactive guidance throughout the document creation process
-
-Interaction Guidelines:
-- Engage users in a professional yet friendly manner
-- Ask clarifying questions to understand specific documentation needs
-- Suggest appropriate skills and workflows based on user requests
-- Provide clear explanations of available capabilities and processes
-- Maintain context throughout multi-step documentation tasks
-- Offer proactive suggestions for improving document quality and structure
-
-<skill_usage>
-- afs_xxx skills: AFS(AIGNE File System) skills provide capabilities to explore, read, write and manage files and virtual modules within the AIGNE environment.
-  You can use these skills to access source files and other resources needed for documentation tasks.
-- listDocuments: This skill lists all available documentation files in the system.
-  You can use this skill to get an overview of existing documents before creating or modifying documentation. for documentation tasks,
-  you should use this skill rather than afs_read to list documentation files.
-- generateDocument: This skill generates new documentation or updates existing documents structure based on user inputs and specifications,
-  You can use this skill to create comprehensive documents from scratch or based on existing templates or update document structure as per user requirements.
-- updateDocument: This skill updates existing documentation content with new information or revisions provided by the user.
-  You can use this skill to refine and enhance documents content based on feedback or additional details.
-- publish: This skill publishes completed documentation to an online website to make it accessible to the intended audience.
-  You can use this skill to manage the publication process and ensure documents are properly formatted and available.
-- translate: This skill translates documentation content into different languages for localization purposes.
-  You can use this skill to adapt documents for diverse audiences by providing translations in the required languages.
-</skill_usage>
-
-<output_requirements>
-- respect tools results and do not fabricate information, use tools results to answer user questions whenever possible
-- Use markdown format for all responses
-- Respond in the same language as the user
-</output_requirements>

package/agents/chat/index.mjs

@@ -1,59 +0,0 @@
-import { mkdir, readFile } from "node:fs/promises";
-import { parse } from "yaml";
-
-await mkdir(".aigne/doc-smith", { recursive: true });
-const config = await readFile(".aigne/doc-smith/config.yaml", "utf-8")
-  .then((raw) => parse(raw))
-  .catch(() => null);
-
-const docsDir = config?.docsDir || ".aigne/doc-smith/docs";
-await mkdir(docsDir, { recursive: true });
-
-export default {
-  type: "ai",
-  name: "chat",
-  description: "Start interactive document generation assistant",
-  instructions: {
-    url: "./chat-system.md",
-  },
-  input_key: "message",
-  afs: {
-    modules: [
-      {
-        module: "history",
-        options: {
-          storage: {
-            url: "file:.aigne/doc-smith/.local/afs-storage.sqlite3",
-          },
-        },
-      },
-      {
-        module: "system-fs",
-        options: {
-          name: "source",
-          localPath: ".",
-          description: "Project root directory for document generation",
-        },
-      },
-      {
-        module: "system-fs",
-        options: {
-          name: "docs",
-          localPath: docsDir,
-          description: "Generated documentation files directory",
-        },
-      },
-    ],
-  },
-  afs_config: {
-    inject_history: true,
-  },
-  skills: [
-    "./skills/list-documents.mjs",
-    "./skills/generate-document.yaml",
-    "./skills/update-document.yaml",
-    "../publish/index.yaml",
-    "../localize/index.yaml",
-    "../utils/exit.mjs",
-  ],
-};

package/agents/chat/skills/generate-document.yaml

@@ -1,15 +0,0 @@
-type: team
-name: generateDocument
-description: Generate complete documentation for your project, or update/delete existing documents or structure based on user feedback
-input_schema:
-  type: object
-  properties:
-    feedback:
-      type: string
-      description: How to generate or update the document content
-  required:
-    - feedback
-skills:
-  - url: ../../create/index.yaml
-    default_input:
-      isChat: true

package/agents/chat/skills/list-documents.mjs

@@ -1,15 +0,0 @@
-import { getMainLanguageFiles } from "../../../utils/docs-finder-utils.mjs";
-import init from "../../init/index.mjs";
-
-export default async function listDocuments(_, options) {
-  const config = await init({ checkOnly: true }, options);
-
-  // Get all main language .md files in docsDir
-  const mainLanguageFiles = await getMainLanguageFiles(config.docsDir, config.locale);
-
-  return {
-    documents: mainLanguageFiles,
-  };
-}
-
-listDocuments.description = "List all available documentation files";

package/agents/chat/skills/update-document.yaml

@@ -1,24 +0,0 @@
-type: team
-name: updateDocument
-description: Update a existing document based on user feedback
-input_schema:
-  type: object
-  properties:
-    docs:
-      type: array
-      items:
-        type: string
-      description: Documents to update, must from listDocuments output
-    feedback:
-      type: string
-      description: Tell us what to change in this content
-    reset:
-      type: boolean
-      description: Regenerate the document from scratch, ignoring previous versions
-  required:
-    - docs
-    - feedback
-skills:
-  - url: ../../update/index.yaml
-    default_input:
-      isChat: true

package/agents/clear/clear-document-config.mjs

@@ -1,36 +0,0 @@
-import { rm } from "node:fs/promises";
-import { pathExists, toDisplayPath, getConfigFilePath } from "../../utils/file-utils.mjs";
-
-export default async function clearDocumentConfig({ workDir }) {
-  const documentConfigPath = getConfigFilePath(workDir);
-  const displayPath = toDisplayPath(documentConfigPath);
-
-  try {
-    const existed = await pathExists(documentConfigPath);
-    await rm(documentConfigPath, { recursive: true, force: true });
-
-    const message = existed
-      ? `⚙️ Cleared document configuration (${displayPath})`
-      : `⚙️ Document configuration already empty (${displayPath})`;
-
-    const suggestions = existed
-      ? ["Run `aigne doc init` to generate a fresh configuration file."]
-      : [];
-
-    return {
-      message,
-      cleared: existed,
-      path: displayPath,
-      suggestions,
-    };
-  } catch (error) {
-    return {
-      message: `⚠️ Failed to clear document configuration: ${error.message}`,
-      error: true,
-      path: displayPath,
-    };
-  }
-}
-
-clearDocumentConfig.taskTitle = "Clear document configuration";
-clearDocumentConfig.description = "Clear the document configuration file";

package/agents/clear/clear-document-structure.mjs

@@ -1,102 +0,0 @@
-import { rm } from "node:fs/promises";
-import { pathExists, toDisplayPath, getStructurePlanPath } from "../../utils/file-utils.mjs";
-
-export default async function clearDocumentStructure(input = {}, _options = {}) {
-  const { docsDir, workDir } = input;
-
-  const structurePlanPath = getStructurePlanPath(workDir);
-
-  const results = [];
-  let hasError = false;
-
-  // Clear structure-plan.json
-  try {
-    const structureExists = await pathExists(structurePlanPath);
-    await rm(structurePlanPath, { force: true });
-
-    const structureDisplayPath = toDisplayPath(structurePlanPath);
-    const structureMessage = structureExists
-      ? `✔ Cleared documentation structure (${structureDisplayPath})`
-      : `• Documentation structure already empty (${structureDisplayPath})`;
-
-    results.push({
-      type: "structure",
-      cleared: structureExists,
-      message: structureMessage,
-    });
-  } catch (error) {
-    hasError = true;
-    results.push({
-      type: "structure",
-      error: true,
-      message: `✗ Failed to clear documentation structure: ${error.message}`,
-    });
-  }
-
-  // Clear documents directory if provided
-  if (docsDir) {
-    try {
-      const docsExists = await pathExists(docsDir);
-      await rm(docsDir, { recursive: true, force: true });
-
-      const docsDisplayPath = toDisplayPath(docsDir);
-      const docsMessage = docsExists
-        ? `✔ Cleared documents directory (${docsDisplayPath})`
-        : `• Documents directory already empty (${docsDisplayPath})`;
-
-      results.push({
-        type: "documents",
-        cleared: docsExists,
-        message: docsMessage,
-      });
-    } catch (error) {
-      hasError = true;
-      results.push({
-        type: "documents",
-        error: true,
-        message: `✗ Failed to clear documents directory: ${error.message}`,
-      });
-    }
-  }
-
-  // Prepare summary message
-  const clearedItems = results.filter((r) => r.cleared).length;
-  const errorItems = results.filter((r) => r.error).length;
-
-  let header;
-  if (errorItems > 0) {
-    header = "⚠️ Documentation Structure cleanup finished with some issues.";
-  } else if (clearedItems > 0) {
-    header = "📖 Documentation Structure cleared successfully!";
-  } else {
-    header = "📖 Documentation Structure already empty.";
-  }
-
-  const detailLines = results.map((item) => `  ${item.message}`).join("\n");
-  const message = [header, "", detailLines].filter(Boolean).join("\n");
-
-  return {
-    message,
-    results,
-    hasError,
-    clearedCount: clearedItems,
-  };
-}
-
-clearDocumentStructure.input_schema = {
-  type: "object",
-  properties: {
-    docsDir: {
-      type: "string",
-      description: "The documents directory to clear (optional)",
-    },
-    workDir: {
-      type: "string",
-      description: "The working directory (defaults to current directory)",
-    },
-  },
-};
-
-clearDocumentStructure.taskTitle = "Clear documentation structure and all generated documents";
-clearDocumentStructure.description =
-  "Clear the documentation structure (structure-plan.json) and optionally the documents directory";