lilflow 0.1.0

package/src/init-project.js

@@ -0,0 +1,573 @@
+import { access, mkdir, readFile, readdir, rename, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import readline from "node:readline/promises";
+import { ConfigError, getConfigTemplate, loadConfig } from "./config.js";
+
+const WORKFLOW_TEMPLATE = `name: hello-world
+version: "1.0"
+
+steps:
+  - name: greet
+    run: echo "Hello, World!"
+`;
+
+const TEMPLATE_PLACEHOLDER_PATTERN =
+  /\{\{\s*(template|config)\.([A-Za-z_][A-Za-z0-9_.-]*)(?:\|([^}]+))?\s*\}\}/g;
+const TEMPLATE_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
+
+/**
+ * Return the help text for `flow init`.
+ *
+ * @returns {string} Command help text.
+ */
+export function getInitHelpText() {
+  return `flow init
+
+Usage:
+  flow init
+  flow init --template <name>
+  flow init --list-templates
+  flow init --help
+
+Options:
+  --template <name>   Initialize workflow.yaml from .flow/templates/<name>/workflow.yaml
+  --list-templates    List available local workflow templates
+  --help              Show this help text
+
+Template Placeholders:
+  {{template.name}}             Prompt for a value
+  {{template.name|default}}     Prompt and fall back to the provided default
+  {{config.parallelism}}        Fill from the resolved flow config
+
+Examples:
+  flow init
+  flow init --template ci-pipeline
+  flow init --list-templates`;
+}
+
+/**
+ * Parse CLI args passed to `flow init`.
+ *
+ * @param {string[]} args - CLI args after `init`.
+ * @returns {{help: boolean, listTemplates: boolean, template: string | undefined}} Parsed args.
+ */
+export function parseInitCommandArgs(args) {
+  const parsed = {
+    help: false,
+    listTemplates: false,
+    template: undefined
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--help" || arg === "-h") {
+      parsed.help = true;
+      continue;
+    }
+
+    if (arg === "--list-templates") {
+      parsed.listTemplates = true;
+      continue;
+    }
+
+    if (arg === "--template") {
+      const templateName = args[index + 1];
+
+      if (!templateName || templateName.startsWith("--")) {
+        throw new ConfigError("flow init --template requires a template name.");
+      }
+
+      if (parsed.template !== undefined) {
+        throw new ConfigError("flow init accepts at most one --template value.");
+      }
+
+      parsed.template = validateTemplateName(templateName);
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--template=")) {
+      const templateName = arg.slice("--template=".length);
+
+      if (templateName.length === 0) {
+        throw new ConfigError("flow init --template requires a template name.");
+      }
+
+      if (parsed.template !== undefined) {
+        throw new ConfigError("flow init accepts at most one --template value.");
+      }
+
+      parsed.template = validateTemplateName(templateName);
+      continue;
+    }
+
+    throw new ConfigError(`Unknown init flag: ${arg}`);
+  }
+
+  if (parsed.help && (parsed.listTemplates || parsed.template !== undefined)) {
+    throw new ConfigError("flow init --help cannot be combined with other flags.");
+  }
+
+  if (parsed.listTemplates && parsed.template !== undefined) {
+    throw new ConfigError("flow init cannot combine --list-templates with --template.");
+  }
+
+  return parsed;
+}
+
+/**
+ * Check whether a directory looks like a git repository root.
+ *
+ * @param {string} cwd - Directory to inspect.
+ * @returns {Promise<boolean>} True when `.git` exists.
+ */
+export async function isGitRepository(cwd) {
+  try {
+    const gitPath = path.join(cwd, ".git");
+    const gitStats = await stat(gitPath);
+    return gitStats.isDirectory() || gitStats.isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Write a file atomically only when it is currently missing.
+ *
+ * @param {string} filePath - Target file path.
+ * @param {string} content - File content to write.
+ * @returns {Promise<boolean>} True when a new file was created.
+ */
+export async function writeFileIfMissing(filePath, content) {
+  try {
+    await access(filePath, constants.F_OK);
+    return false;
+  } catch {
+    const tempPath = `${filePath}.${randomUUID()}.tmp`;
+    await writeFile(tempPath, content, "utf8");
+    await rename(tempPath, filePath);
+    return true;
+  }
+}
+
+/**
+ * Return the local template directory path.
+ *
+ * @param {string} cwd - Repository directory.
+ * @returns {string} Template directory path.
+ */
+export function getTemplateDirectory(cwd) {
+  return path.join(cwd, ".flow", "templates");
+}
+
+/**
+ * Validate and normalize a template name for filesystem use.
+ *
+ * @param {string} templateName - Template name provided by the user.
+ * @returns {string} Validated template name.
+ */
+export function validateTemplateName(templateName) {
+  if (!TEMPLATE_NAME_PATTERN.test(templateName)) {
+    throw new ConfigError(
+      "Template names may only contain letters, numbers, hyphens, and underscores."
+    );
+  }
+
+  return templateName;
+}
+
+/**
+ * Return the workflow file path for a named template.
+ *
+ * @param {string} cwd - Repository directory.
+ * @param {string} templateName - Template name.
+ * @returns {string} Absolute template workflow path.
+ */
+export function getTemplateWorkflowPath(cwd, templateName) {
+  return path.join(getTemplateDirectory(cwd), validateTemplateName(templateName), "workflow.yaml");
+}
+
+/**
+ * List available local workflow templates.
+ *
+ * @param {string} cwd - Repository directory.
+ * @returns {Promise<string[]>} Sorted template names.
+ */
+export async function listWorkflowTemplates(cwd) {
+  const templateDirectory = getTemplateDirectory(cwd);
+
+  try {
+    const entries = await readdir(templateDirectory, { withFileTypes: true });
+    const templateNames = [];
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+
+      try {
+        await access(getTemplateWorkflowPath(cwd, entry.name), constants.F_OK);
+        templateNames.push(entry.name);
+      } catch {
+        continue;
+      }
+    }
+
+    return templateNames.sort((left, right) => left.localeCompare(right));
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return [];
+    }
+
+    throw error;
+  }
+}
+
+/**
+ * Resolve a dot-path inside an object.
+ *
+ * @param {object} source - Object to inspect.
+ * @param {string} dotPath - Dot-separated key path.
+ * @returns {unknown} Resolved value or undefined.
+ */
+function getValueAtPath(source, dotPath) {
+  return dotPath.split(".").reduce((value, segment) => {
+    if (value == null || typeof value !== "object" || !Object.hasOwn(value, segment)) {
+      return undefined;
+    }
+
+    return value[segment];
+  }, source);
+}
+
+/**
+ * Convert a template placeholder value into a string.
+ *
+ * @param {unknown} value - Placeholder value.
+ * @returns {string} Serializable string value.
+ */
+function formatTemplateValue(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+
+  throw new ConfigError("Template placeholders must resolve to string, number, or boolean values.");
+}
+
+/**
+ * Build the default template prompt implementation.
+ *
+ * @param {object} options - Prompt wiring.
+ * @param {NodeJS.ReadableStream} options.stdin - Input stream.
+ * @param {NodeJS.WritableStream} options.stdoutStream - Output stream.
+ * @returns {(variableName: string, defaultValue?: string) => Promise<string>} Prompt function.
+ */
+function createTemplatePrompt({ stdin, stdoutStream }) {
+  return async (variableName, defaultValue) => {
+    const prompt =
+      defaultValue === undefined
+        ? `Template value for '${variableName}': `
+        : `Template value for '${variableName}' [${defaultValue}]: `;
+    const interfaceHandle = readline.createInterface({
+      input: stdin,
+      output: stdoutStream
+    });
+
+    try {
+      const answer = (await interfaceHandle.question(prompt)).trim();
+
+      if (answer.length > 0) {
+        return answer;
+      }
+
+      if (defaultValue !== undefined) {
+        return defaultValue;
+      }
+
+      throw new ConfigError(`Template variable '${variableName}' requires a value.`);
+    } finally {
+      interfaceHandle.close();
+    }
+  };
+}
+
+/**
+ * Resolve template placeholders in template content.
+ *
+ * @param {string} content - Raw template content.
+ * @param {object} options - Resolution options.
+ * @param {object} options.config - Resolved flow config for config placeholders.
+ * @param {(variableName: string, defaultValue?: string) => Promise<string>} options.prompt - Prompt function.
+ * @param {Record<string, string | undefined>} [options.templateValues={}] - Pre-supplied template variable values.
+ * @returns {Promise<string>} Resolved template content.
+ */
+export async function resolveTemplatePlaceholders(content, options) {
+  const {
+    config,
+    prompt,
+    templateValues = {}
+  } = options;
+  const matches = Array.from(content.matchAll(TEMPLATE_PLACEHOLDER_PATTERN));
+
+  if (matches.length === 0) {
+    return content;
+  }
+
+  const resolvedTemplateValues = new Map();
+  let resolvedContent = "";
+  let lastIndex = 0;
+
+  for (const match of matches) {
+    const [placeholder, sourceType, variableName, defaultValue] = match;
+    resolvedContent += content.slice(lastIndex, match.index);
+
+    if (sourceType === "config") {
+      const configuredValue = getValueAtPath(config, variableName);
+
+      if (configuredValue === undefined) {
+        if (defaultValue !== undefined) {
+          resolvedContent += defaultValue.trim();
+        } else {
+          throw new ConfigError(`Template config value '${variableName}' is not defined.`);
+        }
+      } else {
+        resolvedContent += formatTemplateValue(configuredValue);
+      }
+    } else {
+      if (!resolvedTemplateValues.has(variableName)) {
+        const providedValue = templateValues[variableName];
+        resolvedTemplateValues.set(
+          variableName,
+          providedValue !== undefined ? providedValue : await prompt(variableName, defaultValue?.trim())
+        );
+      }
+
+      resolvedContent += resolvedTemplateValues.get(variableName);
+    }
+
+    lastIndex = match.index + placeholder.length;
+  }
+
+  resolvedContent += content.slice(lastIndex);
+  return resolvedContent;
+}
+
+/**
+ * Load and render a named workflow template.
+ *
+ * @param {object} options - Template load options.
+ * @param {string} options.cwd - Repository directory.
+ * @param {string} options.templateName - Template name.
+ * @param {object} options.config - Resolved flow config.
+ * @param {(variableName: string, defaultValue?: string) => Promise<string>} options.prompt - Prompt function.
+ * @param {Record<string, string | undefined>} [options.templateValues] - Pre-supplied template variable values.
+ * @returns {Promise<string>} Resolved workflow content.
+ */
+export async function loadWorkflowTemplate(options) {
+  const {
+    cwd,
+    templateName,
+    config,
+    prompt,
+    templateValues
+  } = options;
+  const templatePath = getTemplateWorkflowPath(cwd, templateName);
+  let content;
+
+  try {
+    content = await readFile(templatePath, "utf8");
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      throw new ConfigError(
+        `Template '${templateName}' was not found at ${templatePath}. Run 'flow init --list-templates' to inspect available templates.`
+      );
+    }
+
+    throw error;
+  }
+
+  return resolveTemplatePlaceholders(content, {
+    config,
+    prompt,
+    templateValues
+  });
+}
+
+/**
+ * Execute the `flow init` command.
+ *
+ * @param {string[]} args - CLI args after `init`.
+ * @param {(message: string) => void} [stdout=console.log] - Success output writer.
+ * @param {(message: string) => void} [stderr=console.error] - Error output writer.
+ * @param {object} [options={}] - Runtime overrides used by tests.
+ * @param {string} [options.cwd=process.cwd()] - Target working directory.
+ * @param {object} [options.env=process.env] - Environment override.
+ * @param {string} [options.homeDir] - Home directory override.
+ * @param {NodeJS.ReadableStream} [options.stdin=process.stdin] - Prompt input stream.
+ * @param {NodeJS.WritableStream} [options.stdoutStream=process.stdout] - Prompt output stream.
+ * @param {Record<string, string | undefined>} [options.templateValues] - Pre-supplied template values.
+ * @param {(variableName: string, defaultValue?: string) => Promise<string>} [options.prompt] - Prompt override.
+ * @returns {Promise<number>} Process exit code.
+ */
+export async function runInitCommand(args, stdout = console.log, stderr = console.error, options = {}) {
+  try {
+    const parsed = parseInitCommandArgs(args);
+
+    if (parsed.help) {
+      stdout(getInitHelpText());
+      return 0;
+    }
+
+    if (parsed.listTemplates) {
+      const templateNames = await listWorkflowTemplates(options.cwd ?? process.cwd());
+
+      if (templateNames.length === 0) {
+        stdout("No workflow templates found in .flow/templates/.");
+        return 0;
+      }
+
+      stdout("Available workflow templates:");
+
+      for (const templateName of templateNames) {
+        stdout(`- ${templateName}`);
+      }
+
+      return 0;
+    }
+
+    return initializeProject({
+      ...options,
+      stdout,
+      stderr,
+      template: parsed.template
+    });
+  } catch (error) {
+    if (error instanceof ConfigError) {
+      stderr(`Error: ${error.message}`);
+      return 1;
+    }
+
+    throw error;
+  }
+}
+
+/**
+ * Ensure flow-generated local state is present in `.gitignore` without duplicating entries.
+ *
+ * @param {string} cwd - Repository directory.
+ * @returns {Promise<boolean>} True when `.gitignore` was modified.
+ */
+export async function ensureGitignoreContainsFlow(cwd) {
+  const gitignorePath = path.join(cwd, ".gitignore");
+  let existing = "";
+
+  try {
+    existing = await readFile(gitignorePath, "utf8");
+  } catch {
+    existing = "";
+  }
+
+  const lines = existing.split(/\r?\n/).filter(Boolean);
+  const requiredEntries = [".flow/", "workflow.local.yaml"];
+  const missingEntries = requiredEntries.filter((entry) => !lines.includes(entry));
+
+  if (missingEntries.length === 0) {
+    return false;
+  }
+
+  const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  await writeFile(gitignorePath, `${existing}${prefix}${missingEntries.join("\n")}\n`, "utf8");
+  return true;
+}
+
+/**
+ * Initialize the repo-local flow project structure.
+ *
+ * @param {object} options - Initialization options.
+ * @param {string} [options.cwd=process.cwd()] - Target working directory.
+ * @param {(message: string) => void} [options.stdout=console.log] - Success output writer.
+ * @param {(message: string) => void} [options.stderr=console.error] - Error output writer.
+ * @returns {Promise<number>} Process exit code.
+ */
+export async function initializeProject(options = {}) {
+  const {
+    cwd = process.cwd(),
+    env = process.env,
+    homeDir,
+    stdin = process.stdin,
+    stdoutStream = process.stdout,
+    template,
+    templateValues,
+    prompt,
+    stdout = console.log,
+    stderr = console.error
+  } = options;
+  let config;
+
+  try {
+    ({ config } = await loadConfig({ cwd, env, homeDir }));
+  } catch (error) {
+    if (error instanceof ConfigError) {
+      stderr(`Error: ${error.message}`);
+      return 1;
+    }
+
+    throw error;
+  }
+
+  if (!(await isGitRepository(cwd))) {
+    stderr("Error: flow init must be run inside a git repository.");
+    return 1;
+  }
+
+  const flowDir = path.join(cwd, ".flow");
+  const runsDir = path.join(flowDir, "runs");
+  const configPath = path.join(flowDir, "config.yaml");
+  const workflowPath = path.join(cwd, "workflow.yaml");
+  const resolvedPrompt = prompt ?? createTemplatePrompt({ stdin, stdoutStream });
+  const workflowContent =
+    template === undefined
+      ? WORKFLOW_TEMPLATE
+      : await loadWorkflowTemplate({
+          cwd,
+          templateName: template,
+          config,
+          prompt: resolvedPrompt,
+          templateValues
+        });
+
+  await mkdir(runsDir, { recursive: true });
+
+  const createdConfig = await writeFileIfMissing(configPath, getConfigTemplate());
+  const createdWorkflow = await writeFileIfMissing(workflowPath, workflowContent);
+  const updatedGitignore = await ensureGitignoreContainsFlow(cwd);
+  const alreadyInitialized = !createdConfig && !createdWorkflow && !updatedGitignore;
+
+  if (alreadyInitialized) {
+    stdout("Flow project already initialized.");
+    stdout(`Workflow file: ${workflowPath}`);
+    stdout("Run 'flow run' to execute your first workflow.");
+    return 0;
+  }
+
+  stdout("✓ Initialized flow project in .flow/");
+  if (template !== undefined) {
+    stdout(`Template: ${template}`);
+  }
+  stdout(`Workflow file: ${workflowPath}`);
+  stdout(`Project config: ${configPath}`);
+  stdout("Run 'flow run' to execute your first workflow.");
+  return 0;
+}
+
+export const templates = {
+  workflow: WORKFLOW_TEMPLATE,
+  config: getConfigTemplate()
+};