@alloy-js/core 0.19.0-dev.3 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alloy-js/core",
-  "version": "0.19.0-dev.3",
+  "version": "0.19.0",
   "description": "",
   "main": "./dist/src/index.js",
   "exports": {
@@ -26,8 +26,8 @@
     }
   },
   "browser": {
-    "./dist/src/write-output.js": "./dist/src/write-output.browser.js",
-    "./src/write-output.ts": "./src/write-output.browser.ts"
+    "./dist/src/host/alloy-host.js": "./dist/src/host/alloy-host.browser.js",
+    "./src/host/alloy-host.ts": "./src/host/alloy-host.browser.ts"
   },
   "keywords": [],
   "author": "brian.terlson@microsoft.com",
@@ -40,14 +40,14 @@
     "prettier": "^3.5.3"
   },
   "devDependencies": {
-    "@alloy-js/cli": "~0.18.0 || >= 0.19.0-dev.0",
-    "@alloy-js/rollup-plugin": "~0.1.0 || >= 0.1.1-dev.0",
     "@microsoft/api-extractor": "~7.52.8",
     "@rollup/plugin-typescript": "^12.1.2",
     "concurrently": "^9.1.2",
     "typescript": "^5.8.3",
     "vite": "^6.2.6",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "@alloy-js/cli": "~0.19.0",
+    "@alloy-js/rollup-plugin": "~0.1.0"
   },
   "type": "module",
   "scripts": {

package/src/components/AppendFile.tsx

@@ -0,0 +1,294 @@
+import { computed } from "@vue/reactivity";
+import { join } from "pathe";
+import { useContext } from "../context.js";
+import { SourceDirectoryContext } from "../context/source-directory.js";
+import { createFileResource } from "../resource.js";
+import { Children, isComponentCreator } from "../runtime/component.js";
+import { childrenArray } from "../utils.jsx";
+import { SourceFile } from "./SourceFile.jsx";
+
+// Regular expression for finding all sigils at once
+const SIGIL_REGEX = /^(\s*)(.*alloy-(.+)-(start|end).*)$/gm;
+
+interface SigilInfo {
+  id: string;
+  start: number | null;
+  end: number | null;
+}
+
+export interface AppendFileProps {
+  /**
+   * The path to the file to read and append content to.
+   */
+  path: string;
+
+  /**
+   * List of region IDs to append to. Defaults to ["append"] if not specified.
+   * Each region corresponds to an AppendRegion child component.
+   */
+  regions?: string[];
+
+  /**
+   * AppendRegion children components that define content to append.
+   */
+  children?: Children;
+}
+
+/**
+ * A component that reads a file and returns content with new content appended
+ * at the end or within specific regions marked by alloy-\{region name\}-start/alloy-\{region name\}-end sigils.
+ *
+ * The component can append content in two ways:
+ * 1. **Simple append**: Content is appended to the end of the file
+ * 2. **Region-based append**: Content is appended before the end sigil on its own line
+ *
+ * Region sigils are line-based - any line containing "alloy-\{region name\}-start" or "alloy-\{region name\}-end"
+ * is considered a sigil.
+ *
+ * @example
+ * Simple append to end of file:
+ * ```tsx
+ * <AppendFile path="output.txt">
+ *   <AppendRegion id="append">New content to add</AppendRegion>
+ * </AppendFile>
+ *
+ * // Returns:
+ * //   Original file content
+ * //   New content to add
+ * ```
+ *
+ * @example
+ * Append to specific regions:
+ * ```tsx
+ * // File content before:
+ * // Header content
+ * // <!-- alloy-main-start -->
+ * // <!-- alloy-main-end -->
+ * // Footer content
+ *
+ * <AppendFile path="template.html" regions={["main"]}>
+ *   <AppendRegion id="main">New main content</AppendRegion>
+ * </AppendFile>
+ *
+ * // Returns:
+ * //   Header content
+ * //   <!-- alloy-main-start -->
+ * //   New main content
+ * //   <!-- alloy-main-end -->
+ * //   Footer content
+ * ```
+ */
+export function AppendFile(props: AppendFileProps): Children {
+  const regions = props.regions || ["append"];
+
+  // Get all children and filter for AppendRegion components
+  const children = childrenArray(() => props.children);
+  const appendRegions: Record<string, Children> = {};
+
+  // Check if we have any AppendRegion components
+  let hasAppendRegions = false;
+  for (const child of children) {
+    if (isComponentCreator(child, AppendRegion)) {
+      hasAppendRegions = true;
+      const regionProps = child.props as AppendRegionProps;
+      let content: Children;
+
+      if ("children" in regionProps && regionProps.children !== undefined) {
+        content = regionProps.children;
+      } else if ("content" in regionProps) {
+        content = regionProps.content;
+      } else {
+        throw new Error(
+          `AppendRegion "${regionProps.id}" must have either children or content`,
+        );
+      }
+
+      appendRegions[regionProps.id] = content;
+    }
+  }
+
+  // If no AppendRegion components found, treat all children as content for the default "append" region
+  if (!hasAppendRegions && children.length > 0) {
+    appendRegions["append"] = children;
+  }
+
+  // Validate that all requested regions have corresponding AppendRegion children
+  for (const regionId of regions) {
+    if (!(regionId in appendRegions)) {
+      throw new Error(
+        `Region "${regionId}" specified but no corresponding AppendRegion child found`,
+      );
+    }
+  }
+
+  // Read existing file content or start with empty string
+  const parentDirectory = useContext(SourceDirectoryContext)!;
+  const fullPath = join(
+    parentDirectory ? parentDirectory.path : "",
+    props.path,
+  );
+
+  const currentContents = createFileResource(fullPath);
+  const newFileContent = computed(() => {
+    if (currentContents.loading) {
+      return;
+    }
+
+    const fileContent = currentContents.error ? "" : currentContents.data!;
+
+    // Find all sigils in the file
+    const sigilInfo: Record<string, SigilInfo> = {};
+    const endSigils: Array<{
+      regionId: string;
+      index: number;
+      indent: string;
+      line: string;
+    }> = [];
+
+    // Reset regex and find all sigils
+    SIGIL_REGEX.lastIndex = 0;
+    let match;
+    while ((match = SIGIL_REGEX.exec(fileContent)) !== null) {
+      const indent = match[1];
+      const fullLine = match[0];
+      const regionId = match[3];
+      const sigilType = match[4];
+      const index = match.index!;
+
+      // Initialize sigil info for this region if not exists
+      if (!sigilInfo[regionId]) {
+        sigilInfo[regionId] = { id: regionId, start: null, end: null };
+      }
+
+      if (sigilType === "start") {
+        sigilInfo[regionId].start = index;
+      } else if (sigilType === "end") {
+        sigilInfo[regionId].end = index;
+
+        // If this is a region we care about, track it for processing
+        if (regions.includes(regionId)) {
+          endSigils.push({
+            regionId,
+            index,
+            indent,
+            line: fullLine,
+          });
+        }
+      }
+    }
+
+    // Validate regions - check for unclosed regions
+    for (const regionId of regions) {
+      const info = sigilInfo[regionId];
+      if (info && info.start !== null && info.end === null) {
+        throw new Error(
+          `Region "${regionId}" has start sigil but no corresponding end sigil`,
+        );
+      }
+    }
+
+    // Check if we have any sigils to process
+    if (endSigils.length === 0) {
+      // No sigils found, append all regions to the end
+      const result: Children[] = [fileContent];
+      for (const regionId of regions) {
+        if (fileContent && !fileContent.endsWith("\n")) {
+          result.push("\n");
+        }
+        result.push(appendRegions[regionId]);
+      }
+      return (
+        <SourceFile path={props.path} filetype="text/plain">
+          {result}
+        </SourceFile>
+      );
+    }
+
+    // Sort end sigils by their position in the file
+    endSigils.sort((a, b) => a.index - b.index);
+
+    // Process content with sigils
+    const result: Children[] = [];
+    let lastIndex = 0;
+
+    // Process each end sigil in order
+    for (const { regionId, index, indent, line } of endSigils) {
+      // Add content before this sigil
+      if (index > lastIndex) {
+        const beforeContent = fileContent.substring(lastIndex, index);
+        if (beforeContent) {
+          result.push(beforeContent);
+        }
+      }
+
+      // Add the new content with proper indentation
+      result.push(indent);
+      result.push(appendRegions[regionId]);
+      result.push("\n");
+
+      // Add the sigil line
+      result.push(line);
+
+      // Update last processed index
+      lastIndex = index + line.length;
+    }
+
+    // Add any remaining content after the last sigil
+    if (lastIndex < fileContent.length) {
+      const remainingPart = fileContent.substring(lastIndex);
+      if (remainingPart) {
+        result.push(remainingPart);
+      }
+    }
+    return result;
+  });
+
+  return (
+    <SourceFile path={props.path} filetype="text/plain">
+      {newFileContent}
+    </SourceFile>
+  );
+}
+
+export interface AppendRegionPropsWithChildren {
+  /**
+   * The ID of the region.
+   */
+  id: string;
+
+  /**
+   * The content to append to the region.
+   */
+  children: Children;
+}
+
+export interface AppendRegionPropsWithContent {
+  /**
+   * The ID of the region.
+   */
+  id: string;
+
+  /**
+   * The content to append to the region.
+   */
+  content: Children;
+}
+
+export interface AppendRegionPropsBase {
+  /**
+   * The ID of the region.
+   */
+  id: string;
+}
+
+export type AppendRegionProps =
+  | AppendRegionPropsWithChildren
+  | AppendRegionPropsWithContent
+  | AppendRegionPropsBase;
+
+export function AppendRegion(props: AppendRegionProps) {
+  /**
+   * This component does nothing except hold props which are retrieved by
+   * the `AppendFile` component.
+   */
+}

package/src/components/CopyFile.tsx

@@ -0,0 +1,29 @@
+import { join } from "pathe";
+import { useContext } from "../context.js";
+import { SourceDirectoryContext } from "../context/source-directory.js";
+import { CopyFileContext } from "../context/source-file.js";
+import { getContext } from "../reactivity.js";
+
+export interface CopyFileProps {
+  /**
+   * The path to write the copy to, relative to the containing directory.
+   */
+  path: string;
+
+  /**
+   * The path to the file to copy.
+   */
+  src: string;
+}
+
+export function CopyFile(props: CopyFileProps) {
+  const parentDirectory = useContext(SourceDirectoryContext)!;
+  const context: CopyFileContext = {
+    path: join(parentDirectory ? parentDirectory.path : "", props.path),
+    sourcePath: props.src,
+  };
+  parentDirectory?.addContent(context);
+  const nodeContext = getContext()!;
+  nodeContext.meta ??= {};
+  nodeContext.meta.copyFile = context;
+}

package/src/components/TemplateFile.tsx

@@ -0,0 +1,193 @@
+import { computed } from "@vue/reactivity";
+import { createFileResource } from "../resource.js";
+import { Children, isComponentCreator } from "../runtime/component.js";
+import { childrenArray } from "../utils.jsx";
+import { SourceFile } from "./SourceFile.jsx";
+
+export interface TemplateFileProps {
+  /**
+   * The path to write the compiled template to.
+   */
+  path: string;
+
+  /**
+   * The file path of the template.
+   */
+  src: string;
+
+  /**
+   * Template variable children components.
+   */
+  children?: Children;
+}
+
+/**
+ * A component that reads a template file and replaces variable placeholders
+ * with actual values.
+ *
+ * Template files can contain variable placeholders in the format
+ * `{{ variable_name }}` which will be replaced with values from `TemplateVariable`
+ * children components. Whitespace around variable names is ignored, so
+ * `{{ name }}`, `{{name}}`, and `{{  name  }}` are all equivalent.
+ *
+ * @example
+ * Basic usage with template variables:
+ * ```tsx
+ * // Template file content (greeting.txt):
+ * // "Hello {{ name }}! You are {{ age }} years old."
+ *
+ * <TemplateFile src="greeting.txt" path="output.txt">
+ *   <TemplateVariable name="name" value="John" />
+ *   <TemplateVariable name="age" value="25" />
+ * </TemplateFile>
+ * ```
+ *
+ * @example
+ * Using children instead of value prop:
+ * ```tsx
+ * // Template file content (welcome.txt):
+ * // "Welcome {{ greeting }}!"
+ *
+ * <TemplateFile src="welcome.txt" path="output.txt">
+ *   <TemplateVariable name="greeting">Hello World</TemplateVariable>
+ * </TemplateFile>
+ * ```
+ *
+ * @example
+ * Complex template with multiple variables:
+ * ```tsx
+ * // Template file content (profile.txt):
+ * // "Name: {{ name }}\nAge: {{ age }}\nLocation: {{ location }}"
+ *
+ * <TemplateFile src="profile.txt" path="profile-output.txt">
+ *   <TemplateVariable name="name" value="Alice" />
+ *   <TemplateVariable name="age">30</TemplateVariable>
+ *   <TemplateVariable name="location" value="New York" />
+ * </TemplateFile>
+ * ```
+ */
+export function TemplateFile(props: TemplateFileProps): Children {
+  // Get all children and filter for TemplateVariable components
+  const children = childrenArray(() => props.children);
+  const templateVariables: Record<string, Children> = {};
+
+  // Extract variable values from TemplateVariable children
+  for (const child of children) {
+    if (!isComponentCreator(child, TemplateVariable)) {
+      continue;
+    }
+
+    const variableProps = child.props as TemplateVariableProps;
+    let value: Children;
+
+    if ("children" in variableProps && variableProps.children !== undefined) {
+      value = variableProps.children;
+    } else if ("value" in variableProps) {
+      value = variableProps.value;
+    } else {
+      throw new Error(
+        `TemplateVariable "${variableProps.name}" must have either children or value`,
+      );
+    }
+
+    templateVariables[variableProps.name] = value;
+  }
+
+  const templateResource = createFileResource(props.src);
+  const fileContent = computed(() => {
+    if (templateResource.loading) {
+      return;
+    }
+
+    if (templateResource.error) {
+      throw new Error(
+        `Failed to read template file "${props.src}": ${templateResource.error}`,
+      );
+    }
+
+    const templateContent = templateResource.data!;
+
+    // Parse template and replace variables
+    const result: Children[] = [];
+    let lastIndex = 0;
+
+    // Match {{ var_name }} patterns
+    const variableRegex = /\{\{\s*(\w+)\s*\}\}/g;
+    let match: RegExpExecArray | null;
+
+    while ((match = variableRegex.exec(templateContent)) !== null) {
+      const [fullMatch, variableName] = match;
+      const matchStart = match.index;
+
+      // Add content before the variable
+      if (matchStart > lastIndex) {
+        const beforeContent = templateContent.slice(lastIndex, matchStart);
+        if (beforeContent) {
+          result.push(beforeContent);
+        }
+      }
+
+      // Add the variable value
+      if (variableName in templateVariables) {
+        result.push(templateVariables[variableName]);
+      } else {
+        throw new Error(
+          `Template variable "${variableName}" not found in TemplateVariable children`,
+        );
+      }
+
+      lastIndex = matchStart + fullMatch.length;
+    }
+
+    // Add remaining content after the last variable
+    if (lastIndex < templateContent.length) {
+      const remainingContent = templateContent.slice(lastIndex);
+      if (remainingContent) {
+        result.push(remainingContent);
+      }
+    }
+
+    return result;
+  });
+
+  return (
+    <SourceFile path={props.path} filetype="text/plain">
+      {fileContent}
+    </SourceFile>
+  );
+}
+
+export interface TemplateVariablePropsWithChildren {
+  /**
+   * The name of the variable.
+   */
+  name: string;
+
+  /**
+   * The value of the variable.
+   */
+  children: Children;
+}
+
+export interface TemplateVariablePropsWithValue {
+  /**
+   * The name of the variable.
+   */
+  name: string;
+
+  /**
+   * The value of the variable.
+   */
+  value: string;
+}
+
+export type TemplateVariableProps =
+  | TemplateVariablePropsWithChildren
+  | TemplateVariablePropsWithValue;
+
+export function TemplateVariable(props: TemplateVariableProps) {
+  /**
+   * This component does nothing except hold props which are retrieved by
+   * the `TemplateFile` component.
+   */
+}

package/src/components/UpdateFile.tsx

@@ -0,0 +1,86 @@
+import { computed } from "@vue/reactivity";
+import { join } from "pathe";
+import { useContext } from "../context.js";
+import { SourceDirectoryContext } from "../context/source-directory.js";
+import { createFileResource } from "../resource.js";
+import { Children } from "../runtime/component.js";
+import { SourceFile } from "./SourceFile.jsx";
+/**
+ * Props for the UpdateFile component.
+ */
+export interface UpdateFileProps {
+  /** The relative path to the file to update or create */
+  path: string;
+  /** Optional path to a file containing default content to use when the target file doesn't exist */
+  defaultContentPath?: string;
+  /** Optional default content to use when the target file doesn't exist */
+  defaultContent?: Children;
+  /** Function that receives the current file contents and returns the new content */
+  children: (currentContents: string | null) => Children;
+}
+
+/**
+ * A component for updating existing files or initializing new files.
+ *
+ * This component allows you to read the current contents of a file and generate
+ * new content based on those contents. If the file doesn't exist, it can use
+ * default content from either a file path or inline content.
+ *
+ * @example
+ * ```tsx
+ * <UpdateFile path="config.json" defaultContent="{}">
+ *   {(currentContents) => {
+ *     const config = currentContents ? JSON.parse(currentContents) : {};
+ *     config.newProperty = "value";
+ *     return JSON.stringify(config, null, 2);
+ *   }}
+ * </UpdateFile>
+ * ```
+ */
+export function UpdateFile(props: UpdateFileProps) {
+  const parentDirectory = useContext(SourceDirectoryContext)!;
+  const fullPath = join(
+    parentDirectory ? parentDirectory.path : "",
+    props.path,
+  );
+  const fileResource = createFileResource(fullPath);
+
+  const newContent = computed(() => {
+    if (fileResource.loading) {
+      return;
+    }
+
+    if (fileResource.error) {
+      if ((fileResource.error as any).code === "ENOENT") {
+        if ("defaultContentPath" in props) {
+          const defaultContentResource = createFileResource(
+            props.defaultContentPath!,
+          );
+          return computed(() => {
+            if (defaultContentResource.loading) {
+              return;
+            }
+
+            if (defaultContentResource.error) {
+              throw defaultContentResource.error;
+            }
+
+            return props.children(defaultContentResource.data!);
+          });
+        } else {
+          return props.children(null);
+        }
+      }
+
+      throw fileResource.error;
+    }
+
+    return props.children(fileResource.data!);
+  });
+
+  return (
+    <SourceFile path={props.path} filetype="text/plain">
+      {newContent}
+    </SourceFile>
+  );
+}

package/src/components/index.tsx

@@ -1,4 +1,6 @@
+export * from "./AppendFile.jsx";
 export * from "./Block.js";
+export * from "./CopyFile.jsx";
 export * from "./Declaration.js";
 export * from "./For.js";
 export * from "./Indent.jsx";
@@ -16,4 +18,6 @@ export * from "./SourceDirectory.js";
 export * from "./SourceFile.js";
 export * from "./StatementList.jsx";
 export * from "./Switch.jsx";
+export * from "./TemplateFile.jsx";
+export * from "./UpdateFile.jsx";
 export * from "./Wrap.jsx";

package/src/components/stc/index.ts

@@ -1,7 +1,9 @@
 import { stc } from "../../stc.js";
 import * as base from "../index.js";
 
+export const AppendFile = stc(base.AppendFile);
 export const Block = stc(base.Block);
+export const CopyFile = stc(base.CopyFile);
 export const Declaration = stc(base.Declaration);
 export const For = stc(base.For);
 export const Indent = stc(base.Indent);
@@ -18,6 +20,8 @@ export const StatementList = stc(base.StatementList);
 export const SourceDirectory = stc(base.SourceDirectory);
 export const SourceFile = stc(base.SourceFile);
 export const Switch = stc(base.Switch);
+export const TemplateFile = stc(base.TemplateFile);
+export const UpdateFile = stc(base.UpdateFile);
 export const Wrap = stc(base.Wrap);
 export const ReferenceOrContent = stc(base.ReferenceOrContent);
 

package/src/context/source-directory.ts

@@ -1,9 +1,11 @@
 import { ComponentContext, createNamedContext } from "../context.js";
-import type { SourceFileContext } from "./source-file.js";
+import type { CopyFileContext, SourceFileContext } from "./source-file.js";
 
 export interface SourceDirectoryContext {
-  contents: (SourceDirectoryContext | SourceFileContext)[];
-  addContent(content: SourceDirectoryContext | SourceFileContext): void;
+  contents: (SourceDirectoryContext | SourceFileContext | CopyFileContext)[];
+  addContent(
+    content: SourceDirectoryContext | SourceFileContext | CopyFileContext,
+  ): void;
   path: string;
 }
 

package/src/context/source-file.ts

@@ -2,6 +2,11 @@ import { ComponentContext, createNamedContext } from "../context.js";
 import type { Refkey } from "../refkey.js";
 import { ComponentDefinition } from "../runtime/component.js";
 
+export interface CopyFileContext {
+  path: string;
+  sourcePath: string;
+}
+
 export interface SourceFileContext {
   path: string;
   filetype: string;