@izara_project/izara-core-generate-service-code 1.0.65 → 1.0.67

package/src/emit/system/emitSystemWebSocketArtifacts.js

@@ -0,0 +1,183 @@
+const SOURCE = 'app/src/generatedCode/SystemFlowSchemas/WebSocketMain/source';
+
+export async function emitSystemWebSocketArtifacts(flows, { includeRelationshipOwnTopic = false } = {}) {
+  if (!hasSystemWebSocket(flows, { includeRelationshipOwnTopic })) return { artifacts: [], functions: [] };
+
+  return {
+    artifacts: [
+      { path: `${SOURCE}/WebSocketConnect.js`, content: webSocketConnect() },
+      { path: `${SOURCE}/WebSocketComplete_Main.js`, content: webSocketCompleteMain() },
+      { path: `${SOURCE}/WebSocketComplete_HdrSqs.js`, content: webSocketCompleteHandler() }
+    ],
+    functions: [
+      renderWebSocketConnectYaml(),
+      renderWebSocketCompleteYaml()
+    ]
+  };
+}
+
+export function systemWebSocketManagedPaths() {
+  return [
+    `${SOURCE}/WebSocketConnect.js`,
+    `${SOURCE}/WebSocketComplete_Main.js`,
+    `${SOURCE}/WebSocketComplete_HdrSqs.js`
+  ];
+}
+
+export function hasSystemWebSocket(flows, { includeRelationshipOwnTopic = false } = {}) {
+  // return true;
+  return Array.isArray(flows) && flows.some(flow => Array.isArray(flow?.event) && (flow.event.includes('s3') || (includeRelationshipOwnTopic && flow.event.includes('ownTopic') && flow.initiateBy === 'user')));
+}
+
+function renderWebSocketConnectYaml() {
+  return `WebSocketConnect:
+  handler: src/generatedCode/SystemFlowSchemas/WebSocketMain/source/WebSocketConnect.main
+  name: \${self:custom.iz_resourcePrefix}WebSocketConnect
+  role: WebSocketMainRole
+  events:
+    - websocket:
+        route: $connect
+    - websocket:
+        route: $disconnect
+    - websocket:
+        route: $default
+`;
+}
+
+function renderWebSocketCompleteYaml() {
+  return `WebSocketCompleteHdrSqs:
+  handler: src/generatedCode/SystemFlowSchemas/WebSocketMain/source/WebSocketComplete_HdrSqs.main
+  name: \${self:custom.iz_resourcePrefix}WebSocketCompleteHdrSqs
+  role: WebSocketMainRole
+  events:
+    - sqs:
+        arn: arn:aws:sqs:\${self:custom.iz_region}:\${self:custom.iz_accountId}:\${self:custom.iz_resourcePrefix}WebSocketCompleteHdrSqs
+        batchSize: 10
+        filterPatterns:
+          - body:
+              MessageAttributes:
+                callingFlow:
+                  Value:
+                    - \${self:custom.iz_resourcePrefix}WebSocketCompleteHdrSqs
+          - body:
+              MessageAttributes:
+                callingFlow:
+                  Value:
+                    - exists: false
+`;
+}
+
+function webSocketConnect() {
+  return `import dynamodbSharedLib from '@izara_project/izara-core-library-dynamodb';
+import { middlewareHandler as middleware, response } from '@izara_project/izara-middleware';
+
+export const main = middleware.wrap(async event => {
+  const { eventType, connectionId } = event.requestContext ?? {};
+  try {
+    event._izContext.logger.debug('Event:', event);
+    if (eventType === 'CONNECT') {
+      const { userId, submittedByUserId } = event.queryStringParameters ?? {};
+      await dynamodbSharedLib.putItem(event._izContext, await dynamodbSharedLib.tableName(event._izContext, 'UserUploadRecords'), {
+        connectionId, userId, submittedByUserId, expirationTime: Math.floor(Date.now() / 1000) + 7200
+      });
+      //(<webSocketConnect>)
+      //(</webSocketConnect>)
+    } else if (eventType === 'DISCONNECT') {
+      await dynamodbSharedLib.deleteItem(event._izContext, await dynamodbSharedLib.tableName(event._izContext, 'UserUploadRecords'), { connectionId });
+      //(<webSocketDisconnect>)
+      //(</webSocketDisconnect>)
+    }
+    return response.webSocketSuccess();
+  } catch (error) {
+    event._izContext.logger.error('Error, WebSocketConnect: ', error);
+    return response.failure(error);
+  }
+});
+`;
+}
+
+function webSocketCompleteMain() {
+  return `import { NoRetryError } from '@izara_project/izara-core-library-core';
+import { consts } from '@izara_project/izara-middleware';
+import { getObjectSchema, utils } from '@izara_project/izara-core-library-service-schemas';
+import dynamodbSharedLib from '@izara_project/izara-core-library-dynamodb';
+import { webSocket } from '@izara_project/izara-core-library-external-request';
+
+const { createFlowTypeConcat } = utils;
+const { postToConnection } = webSocket;
+
+export default async function WebSocketComplete(_izContext, topicArn, requestParams, callingFlowConfig = {}) {
+  try {
+    _izContext.logger.debug('WebSocketComplete _izContext', _izContext);
+    _izContext.logger.debug('WebSocketComplete requestParams', requestParams);
+    _izContext.logger.debug('WebSocketComplete callingFlowConfig', callingFlowConfig);
+    const correlationId = _izContext.correlationIds.get(consts.X_CORRELATION_ID);
+    if (!topicArn) throw new NoRetryError('not have TopicArn for get FlowSchemas');
+    const topicName = topicArn.split(':')[5].split('_');
+    let flowTag = topicName[2];
+    let flowSchema = await getObjectSchema.getFlowSchemaS3WithCache(_izContext, { flowTag, serviceTag: topicName[0] });
+    if (!flowSchema) {
+      if (!requestParams?.hasOwnProperty('flowTag')) throw new NoRetryError('Could not find flowSchema from topicArn or requestParams.flowTag');
+      flowTag = requestParams.flowTag;
+      flowSchema = await getObjectSchema.getFlowSchemaS3WithCache(_izContext, { flowTag, serviceTag: process.env.iz_serviceTag });
+    }
+    //(<createIdentifiersFlow>)
+    let identifiers;
+    //(</createIdentifiersFlow>)
+    let taskKey;
+    if (flowSchema.statusType === 'statusField' || flowSchema.statusType === 'storedCache' || flowSchema.statusType === 'triggerCache') {
+      taskKey = createFlowTypeConcat(_izContext, { flowTag, serviceTag: topicName[0] }) + identifiers;
+    } else if (flowSchema.statusType === 'none') {
+      taskKey = createFlowTypeConcat(_izContext, { flowTag, serviceTag: topicName[0] }) + correlationId;
+    }
+    if (!taskKey) return;
+    const tasks = await dynamodbSharedLib.query(_izContext, await dynamodbSharedLib.tableName(_izContext, 'WebSocketTask'), { taskKey });
+    await Promise.all((tasks.Items ?? []).map(async task => {
+      //(<beforePostMessage>)
+      //(</beforePostMessage>)
+      await postToConnection({ message: requestParams }, task.connectionId);
+      await dynamodbSharedLib.deleteItem(_izContext, await dynamodbSharedLib.tableName(_izContext, 'WebSocketTask'), { taskKey: task.taskKey, connectionId: task.connectionId });
+    }));
+  } catch (error) {
+    _izContext.logger.error('error WebSocketInvoke: ', error);
+    throw error;
+  }
+}
+`;
+}
+
+function webSocketCompleteHandler() {
+  return `import { middlewareHandler as middleware } from '@izara_project/izara-middleware';
+import Logger from '@izara_project/izara-core-library-logger';
+import { recordHandlerSharedLib } from '@izara_project/izara-core-library-record-handler';
+import callingFlowSharedLib from '@izara_project/izara-core-library-calling-flow';
+import WebSocketComplete from './WebSocketComplete_Main.js';
+
+middleware.setValidatorSchema(recordHandlerSharedLib.baseValidatorSchema());
+const perRecordsValidatorSchema = {};
+export const main = middleware.wrap(async (event, context, callback) => {
+  try {
+    const recordPromises = [];
+    await Promise.all(event.Records.map(async record => {
+      record._izContext.logger.debug('record ReceiveMsgOutHdrSqs', record);
+      await recordHandlerSharedLib.validateRecord(record, 'WebSocketCompleteHdrSqs', perRecordsValidatorSchema);
+      recordPromises.push(recordHandlerSharedLib.recordHandler(
+        record,
+        WebSocketComplete,
+        'WebSocketCompleteHdrSqs',
+        [record.body.TopicArn, record.body.Message, callingFlowSharedLib.addCallingFlowToPassOnProperties(record.body.Message)]
+      ));
+    }));
+    try {
+      await Promise.all(recordPromises);
+      return event.Records;
+    } catch {
+      Logger.debug('Promise.all(recordPromises) in handler threw error (at least one record did no resolve)');
+    }
+  } catch (error) {
+    Logger.error('Unhandled Error, WebSocketComplete_HdrSqs: ', error);
+    throw error;
+  }
+});
+`;
+}

package/src/generate.js

@@ -1,130 +1,64 @@
-/*
-Copyright (C) 2020 Sven Mason <http://izara.io>
-
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU Affero General Public License as published by
-the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-GNU Affero General Public License for more details.
-
-You should have received a copy of the GNU Affero General Public License
-along with this program. If not, see <http://www.gnu.org/licenses/>.
-*/
-
-import { join } from 'path';
-import { validator } from '@izara_project/izara-core-library-service-schemas';
-import { basicValidatorSchema } from '@izara_project/izara-shared-service-schemas';
-import { generateCode } from './generateCode.js';
-import { generateSchema } from './generateSchema.js';
-
-const { validateLocalSchema } = validator;
-
-/**
- * High-level API to validate schemas and generate code.
- * Wires legacy Logger and validateLocalSchema.
- *
- * @param {string} rootPath - The root path of the project.
- * @param {object} [options={}] - Configuration options.
- * @param {object} [options.logger] - Logger instance.
- * @param {string} [options.configPath] - Path to the serverless configuration file.
- * @param {string} [options.outputPath] - Output directory path.
- * @param {boolean} [options.skipValidation=false] - Whether to skip schema validation.
- * @param {boolean} [options.skipGenerateSchema=false] - Whether to skip schema generation.
- * @param {boolean} [options.skipGenerateCode=false] - Whether to skip code generation.
- * @param {Array} [options.schemaTemplateConfig] - Schema template configuration.
- * @returns {Promise<{durationMs: number}>} Generation duration details.
- */
-async function generate(rootPath, options = {}) {
-  const {
-    logger = createSilentLogger(),
-    configPath = join(rootPath, 'config', 'serverless.config.yml'),
-    outputPath = rootPath,
-    skipValidation = false,
-    skipGenerateSchema = false,
-    skipGenerateCode = false,
-    schemaTemplateConfig
-  } = options;
-
-  const schemasPath = join(rootPath, 'app', 'src', 'schemas');
-
-  if (!skipGenerateSchema) {
-    await generateSchema(rootPath, {
-      configPath,
-      outputPath,
-      schemaTemplateConfig
-    });
-  }
-
-  if (!skipValidation) {
-    patchFlowStepsValidationSchema();
-
-    console.info('[INFO] [generate] STATUS=VALIDATING | local schemas...');
-    const validateStartTime = Date.now();
-    const result = await validateLocalSchema({ logger }, schemasPath, configPath);
-    const validateDuration = Date.now() - validateStartTime;
-
-    console.info(
-      `[INFO] [generate] STATUS=VALIDATED | errors=${result.validateErrors.length} | elapsedMs=${validateDuration}`
-    );
-
-    if (result.validateErrors.length > 0) {
-      logger.error(
-        'Validation failed with following errors:',
-        result.validateErrors
-      );
-      const err = new Error('Schema validation failed');
-      err.validateErrors = result.validateErrors;
-      throw err;
-    }
-  }
-
-  if (skipGenerateCode) {
-    return { durationMs: 0 };
+import { buildGenerationPlan } from './plan/buildGenerationPlan.js';
+import { commitArtifacts } from './output/commitArtifacts.js';
+import { compileProject } from './compile/compileProject.js';
+import { crudApplicationManagedPaths, emitCrudApplicationArtifacts } from './emit/crud/emitCrudApplicationArtifacts.js';
+import { dynamicCrudFlowSchemaPaths, emitDynamicCrudFlowSchemas } from './emit/crud/emitDynamicCrudFlowSchemas.js';
+import { customFlowApplicationManagedPaths, emitCustomFlowApplicationArtifacts } from './emit/custom/emitCustomFlowApplicationArtifacts.js';
+import { emitDynamicRbacFlowSchemas, rbacFlowSchemaManagedPaths } from './emit/rbac/emitDynamicRbacFlowSchemas.js';
+import { emitRbacApplicationArtifacts, rbacApplicationManagedPaths } from './emit/rbac/emitRbacApplicationArtifacts.js';
+import { dynamicRelationshipFlowSchemaPaths, emitDynamicRelationshipFlowSchemas } from './emit/relationship/emitDynamicRelationshipFlowSchemas.js';
+import { emitRelationshipApplicationArtifacts, relationshipApplicationManagedPaths } from './emit/relationship/emitRelationshipApplicationArtifacts.js';
+import { emitResourceArtifacts, resourceArtifactPaths } from './emit/resource/emitResourceArtifacts.js';
+import { loadLocalSchemaDirectory } from './compile/loadSchemas.js';
+import { emitSystemWebSocketArtifacts, hasSystemWebSocket, systemWebSocketManagedPaths } from './emit/system/emitSystemWebSocketArtifacts.js';
+
+export async function generate(rootPath, options = {}) {
+  const startedAt = Date.now();
+  const logger = options.logger;
+  logger?.info?.(`[INFO] [Generate] STATUS=STARTED | rootPath=${rootPath}`);
+  try {
+    const project = compileProject({ ...options, rootPath });
+    const [objects, relationships, flows] = await Promise.all([
+      loadLocalSchemaDirectory(project, 'ObjectSchemas'),
+      loadLocalSchemaDirectory(project, 'RelationshipSchemas'),
+      loadLocalSchemaDirectory(project, 'FlowSchemas')
+    ]);
+    logger?.debug?.(`[DEBUG] [Generate] STATUS=SCHEMAS_LOADED | objects=${objects.length} relationships=${relationships.length} flows=${flows.length}`);
+    const groups = await emitGroups({ project, objects, relationships, flows });
+    logger?.debug?.(`[DEBUG] [Generate] STATUS=ARTIFACTS_EMITTED | ${groups.map(group => `${group.scope}=${group.artifacts.length}`).join(' ')}`);
+    const files = groups.length === 0
+      ? []
+      : await commitArtifacts(buildGenerationPlan(project, groups.flatMap(group => group.artifacts), {
+        managedScopes: Object.fromEntries(groups.map(group => [group.scope, group.managedPaths]))
+      }));
+    const durationMs = Date.now() - startedAt;
+    logger?.info?.(`[INFO] [Generate] STATUS=FINISHED | files=${files.length} durationMs=${durationMs}`);
+
+    return { project, durationMs, files };
+  } catch (error) {
+    logger?.error?.(`[ERROR] [Generate] STATUS=FAILED | durationMs=${Date.now() - startedAt}`, error);
+    throw error;
   }
-
-  const startTime = Date.now();
-  await generateCode(rootPath, { outputPath, configPath });
-  return { durationMs: Date.now() - startTime };
 }
 
-function patchFlowStepsValidationSchema() {
-  const flowStepsSchema = basicValidatorSchema.basicFlowSchema?.properties?.flowSteps;
-  if (!flowStepsSchema || flowStepsSchema.oneOf || !flowStepsSchema.items) {
-    return;
-  }
-
-  const objectStepSchema = {
-    ...flowStepsSchema.items,
-    required: (flowStepsSchema.items.required || []).filter(
-      item => item !== 'stepName'
-    )
-  };
-
-  basicValidatorSchema.basicFlowSchema.properties.flowSteps = {
-    oneOf: [
-      flowStepsSchema,
-      {
-        type: 'object',
-        minProperties: 1,
-        patternProperties: {
-          [basicValidatorSchema.strNotEmptyRegex]: objectStepSchema
-        }
-      }
-    ]
-  };
+async function emitGroups({ project, objects, relationships, flows }) {
+  const [crud, relationship, rbac, system, resource] = await Promise.all([
+    emitCrudApplicationArtifacts({ objects, flows, serviceTag: project.serviceTag }),
+    emitRelationshipApplicationArtifacts({ relationships, flows, serviceTag: project.serviceTag }),
+    emitRbacApplicationArtifacts(objects),
+    emitSystemWebSocketArtifacts(flows, { includeRelationshipOwnTopic: true }),
+    emitResourceArtifacts({ objects, relationships, flows })
+  ]);
+  const custom = await emitCustomFlowApplicationArtifacts(flows, { systemFunctions: system.functions, objects });
+  return [
+    { scope: 'crud-flow-schemas', managedPaths: dynamicCrudFlowSchemaPaths, artifacts: emitDynamicCrudFlowSchemas({ objects, flows }) },
+    { scope: 'relationship-flow-schemas', managedPaths: dynamicRelationshipFlowSchemaPaths, artifacts: emitDynamicRelationshipFlowSchemas() },
+    { scope: 'rbac-flow-schemas', managedPaths: rbacFlowSchemaManagedPaths(objects), artifacts: await emitDynamicRbacFlowSchemas({ objects, serviceTag: project.serviceTag }) },
+    { scope: 'crud-application', managedPaths: crudApplicationManagedPaths(), artifacts: crud },
+    { scope: 'relationship-application', managedPaths: relationshipApplicationManagedPaths(), artifacts: relationship },
+    { scope: 'rbac-application', managedPaths: rbacApplicationManagedPaths(objects), artifacts: rbac },
+    { scope: 'system-websocket', managedPaths: systemWebSocketManagedPaths(), artifacts: system.artifacts },
+    { scope: 'custom-flow-application', managedPaths: customFlowApplicationManagedPaths(flows, { includeYaml: hasSystemWebSocket(flows, { includeRelationshipOwnTopic: true }) }), artifacts: custom },
+    { scope: 'shared-resources', managedPaths: resourceArtifactPaths, artifacts: resource }
+  ];
 }
-
-function createSilentLogger() {
-  return {
-    debug: () => {},
-    info: () => {},
-    warn: () => {},
-    error: () => {}
-  };
-}
-
-export { generate };

package/src/output/commitArtifacts.js

@@ -0,0 +1,213 @@
+import { constants } from 'node:fs';
+import { copyFile, lstat, mkdir, mkdtemp, readFile, realpath, rename, rm, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+import { normalizeArtifactPaths, validateArtifacts } from './validateArtifacts.js';
+import { mergeHooks } from './mergeHooks.js';
+
+const MANAGED_ARTIFACTS_PATH = '.generate-service-code-v2-managed.json';
+const STAGING_PREFIX = '.generate-service-code-v2-stage-';
+
+export async function commitArtifacts(plan) {
+  if (!plan?.project?.outputPath || !Array.isArray(plan.artifacts)) {
+    throw new TypeError('GenerationPlan must include project.outputPath and artifacts');
+  }
+
+  const outputRoot = resolve(plan.project.outputPath);
+  const artifacts = validateArtifacts(plan.artifacts);
+  await mkdir(outputRoot, { recursive: true });
+  const physicalOutputRoot = await realpath(outputRoot);
+  const manifestPath = await resolveSafeTarget(physicalOutputRoot, MANAGED_ARTIFACTS_PATH);
+  const managedArtifacts = await loadManagedArtifacts(manifestPath);
+  const managedScopes = normalizeManagedScopes(plan);
+  const stalePaths = staleManagedPaths(managedScopes, managedArtifacts, artifacts);
+  const mergedArtifacts = await mergeHooks(physicalOutputRoot, artifacts);
+  const stagedRoot = await mkdtemp(join(physicalOutputRoot, STAGING_PREFIX));
+
+  try {
+    const changes = await stageChanges({
+      outputRoot: physicalOutputRoot,
+      stagedRoot,
+      artifacts: mergedArtifacts,
+      stalePaths,
+      manifestPath,
+      manifestContent: managedScopes
+        ? managedManifestContent(managedScopes, managedArtifacts, mergedArtifacts)
+        : undefined
+    });
+    const snapshots = await snapshotChanges(changes, stagedRoot);
+    try {
+      await applyChanges(changes);
+    } catch (error) {
+      await rollbackChanges(changes, snapshots);
+      throw error;
+    }
+  } finally {
+    await rm(stagedRoot, { recursive: true, force: true });
+  }
+
+  return mergedArtifacts.map(({ path }) => ({ path }));
+}
+
+function normalizeManagedScopes(plan) {
+  if (plan.managedScopes !== undefined) {
+    return plan.managedScopes;
+  }
+  if (plan.managedScope === undefined) {
+    return undefined;
+  }
+  return { [plan.managedScope]: normalizeArtifactPaths(plan.managedPaths ?? []) };
+}
+
+function staleManagedPaths(managedScopes, managedArtifacts, artifacts) {
+  if (!managedScopes) {
+    return [];
+  }
+  const emittedPaths = new Set(artifacts.map(artifact => artifact.path));
+  const stalePaths = new Set();
+  for (const [scope, declaredPaths] of Object.entries(managedScopes)) {
+    if (!Object.hasOwn(managedArtifacts, scope)) {
+      continue;
+    }
+    for (const path of [...declaredPaths, ...managedArtifacts[scope]]) {
+      if (!emittedPaths.has(path)) {
+        stalePaths.add(path);
+      }
+    }
+  }
+  return [...stalePaths];
+}
+
+function managedManifestContent(managedScopes, managedArtifacts, artifacts) {
+  const emittedPaths = new Set(artifacts.map(artifact => artifact.path));
+  const nextManifest = { ...managedArtifacts };
+  for (const [scope, paths] of Object.entries(managedScopes)) {
+    nextManifest[scope] = paths.filter(path => emittedPaths.has(path));
+  }
+  return `${JSON.stringify(nextManifest, null, 2)}\n`;
+}
+
+async function stageChanges({ outputRoot, stagedRoot, artifacts, stalePaths, manifestPath, manifestContent }) {
+  const changes = [];
+  for (const artifact of artifacts) {
+    const targetPath = await resolveSafeTarget(outputRoot, artifact.path);
+    const stagedPath = await resolveSafeTarget(stagedRoot, artifact.path, { createDirectories: true });
+    await writeFile(stagedPath, artifact.content, { encoding: 'utf8', flag: constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW });
+    changes.push({ targetPath, stagedPath });
+  }
+  for (const path of stalePaths) {
+    changes.push({ targetPath: await resolveSafeTarget(outputRoot, path), delete: true });
+  }
+  if (manifestContent !== undefined) {
+    const stagedPath = await resolveSafeTarget(stagedRoot, MANAGED_ARTIFACTS_PATH, { createDirectories: true });
+    await writeFile(stagedPath, manifestContent, 'utf8');
+    changes.push({ targetPath: manifestPath, stagedPath });
+  }
+  return changes;
+}
+
+async function snapshotChanges(changes, stagedRoot) {
+  const snapshots = new Map();
+  for (const [index, change] of changes.entries()) {
+    try {
+      const details = await lstat(change.targetPath);
+      if (!details.isFile()) {
+        throw new Error(`Artifact target is not a file: ${change.targetPath}`);
+      }
+      const backupPath = join(stagedRoot, `backup-${index}`);
+      await copyFile(change.targetPath, backupPath, constants.COPYFILE_EXCL);
+      snapshots.set(change.targetPath, { backupPath });
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        snapshots.set(change.targetPath, null);
+        continue;
+      }
+      throw error;
+    }
+  }
+  return snapshots;
+}
+
+async function applyChanges(changes) {
+  for (const change of changes) {
+    if (change.delete) {
+      await unlink(change.targetPath).catch(ignoreMissingFile);
+      continue;
+    }
+    await mkdir(dirname(change.targetPath), { recursive: true });
+    await rename(change.stagedPath, change.targetPath);
+  }
+}
+
+async function rollbackChanges(changes, snapshots) {
+  for (const change of [...changes].reverse()) {
+    const snapshot = snapshots.get(change.targetPath);
+    if (!snapshot) {
+      await unlink(change.targetPath).catch(ignoreMissingFile);
+      continue;
+    }
+    await mkdir(dirname(change.targetPath), { recursive: true });
+    await copyFile(snapshot.backupPath, change.targetPath);
+  }
+}
+
+function ignoreMissingFile(error) {
+  if (error.code !== 'ENOENT') {
+    throw error;
+  }
+}
+
+async function loadManagedArtifacts(manifestPath) {
+  try {
+    const parsed = JSON.parse(await readFile(manifestPath, 'utf8'));
+    if (!parsed || Array.isArray(parsed) || typeof parsed !== 'object') {
+      throw new TypeError('Managed artifact manifest must be an object');
+    }
+    for (const paths of Object.values(parsed)) {
+      normalizeArtifactPaths(paths);
+    }
+    return parsed;
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return {};
+    }
+    throw error;
+  }
+}
+
+async function resolveSafeTarget(outputRoot, artifactPath, { createDirectories = false } = {}) {
+  const targetPath = resolve(outputRoot, artifactPath);
+  if (relative(outputRoot, targetPath).startsWith('..')) {
+    throw new Error(`Artifact path escapes output root: ${artifactPath}`);
+  }
+
+  let currentPath = outputRoot;
+  for (const segment of dirname(artifactPath).split(sep).filter(Boolean)) {
+    currentPath = join(currentPath, segment);
+    try {
+      const details = await lstat(currentPath);
+      if (details.isSymbolicLink() || !details.isDirectory()) {
+        throw new Error(`Artifact path traverses a non-directory: ${artifactPath}`);
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+      if (!createDirectories) {
+        break;
+      }
+      await mkdir(currentPath, { recursive: true });
+    }
+  }
+
+  try {
+    if ((await lstat(targetPath)).isSymbolicLink()) {
+      throw new Error(`Artifact path targets a symlink: ${artifactPath}`);
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+  return targetPath;
+}

package/src/output/mergeHooks.js

@@ -0,0 +1,55 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { join, sep } from 'node:path';
+
+export async function mergeHooks(outputRoot, artifacts) {
+  return Promise.all(artifacts.map(async artifact => ({
+    ...artifact,
+    content: await mergeHook(outputRoot, artifact)
+  })));
+}
+
+async function mergeHook(outputRoot, artifact) {
+  const parts = artifact.path.split(sep);
+  const sourceIndex = parts.lastIndexOf('source');
+  if (sourceIndex < 0 || sourceIndex === parts.length - 1) {
+    return artifact.content;
+  }
+
+  const hookPath = join(outputRoot, ...parts.slice(0, sourceIndex), 'hook', ...parts.slice(sourceIndex + 1));
+  try {
+    if (!(await lstat(hookPath)).isFile()) {
+      return artifact.content;
+    }
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return artifact.content;
+    }
+    throw error;
+  }
+
+  const matchers = hookMatchers(artifact.path);
+  if (!matchers) {
+    return artifact.content;
+  }
+
+  const hookContent = await readFile(hookPath, 'utf8');
+  return artifact.content.replace(matchers.anyTag, (match, tagName) => (
+    hookContent.match(matchers.tagPattern(tagName))?.[0] ?? match
+  ));
+}
+
+function hookMatchers(filePath) {
+  if (filePath.endsWith('.js')) {
+    return {
+      anyTag: /\/\/\(<(\w+)>\)([\s\S]*?)\/\/\(<\/\1>\)/gm,
+      tagPattern: name => new RegExp(`\\/\\/\\(<${name}>\\)([\\s\\S]*?)\\/\\/\\(<\\/${name}>\\)`, 'gm')
+    };
+  }
+  if (filePath.endsWith('.yml') || filePath.endsWith('.yaml')) {
+    return {
+      anyTag: /#<#(\w+)#>([\s\S]*?)#<#\/\1#>/gm,
+      tagPattern: name => new RegExp(`#<#${name}#>([\\s\\S]*?)#<#\\/${name}#>`, 'gm')
+    };
+  }
+  return null;
+}