poe-code 2.0.3 → 2.0.5

package/dist/services/service-manifest.d.ts

@@ -1,9 +1,13 @@
+import type { CliEnvironment } from "../cli/environment.js";
+import type { CommandContext } from "../cli/context.js";
 import type { FileSystem } from "../utils/file-system.js";
 import { type JsonObject } from "../utils/json.js";
+import { type TomlTable } from "../utils/toml.js";
 type ValueResolver<Options, Value> = Value | ((context: MutationContext<Options>) => Value);
 interface MutationContext<Options> {
     options: Options;
     fs: FileSystem;
+    env: CliEnvironment;
 }
 interface TransformResult {
     content: string | null;
@@ -11,7 +15,7 @@ interface TransformResult {
 }
 interface TransformFileMutation<Options> {
     kind: "transformFile";
-    label?: string;
+    label?: ValueResolver<Options, string | undefined>;
     target: ValueResolver<Options, string>;
     transform(input: {
         content: string | null;
@@ -20,42 +24,48 @@ interface TransformFileMutation<Options> {
 }
 interface EnsureDirectoryMutation<Options> {
     kind: "ensureDirectory";
-    label?: string;
+    label?: ValueResolver<Options, string | undefined>;
     path: ValueResolver<Options, string>;
 }
 interface CreateBackupMutation<Options> {
     kind: "createBackup";
-    label?: string;
+    label?: ValueResolver<Options, string | undefined>;
     target: ValueResolver<Options, string>;
     timestamp?: ValueResolver<Options, (() => string) | undefined>;
 }
 interface WriteTemplateMutation<Options> {
     kind: "writeTemplate";
-    label?: string;
+    label?: ValueResolver<Options, string | undefined>;
     target: ValueResolver<Options, string>;
     templateId: string;
     context?: ValueResolver<Options, JsonObject | undefined>;
 }
 interface RemoveFileMutation<Options> {
     kind: "removeFile";
-    label?: string;
+    label?: ValueResolver<Options, string | undefined>;
     target: ValueResolver<Options, string>;
     whenEmpty?: boolean;
     whenContentMatches?: RegExp;
 }
 export type ServiceMutation<Options> = TransformFileMutation<Options> | EnsureDirectoryMutation<Options> | CreateBackupMutation<Options> | WriteTemplateMutation<Options> | RemoveFileMutation<Options>;
-export interface ServiceManifest<ConfigureOptions, RemoveOptions = ConfigureOptions> {
+export interface ServiceManifestDefinition<ConfigureOptions, RemoveOptions = ConfigureOptions> {
     id: string;
     summary: string;
-    prerequisites?: {
-        before?: string[];
-        after?: string[];
-    };
     configure: ServiceMutation<ConfigureOptions>[];
     remove?: ServiceMutation<RemoveOptions>[];
 }
+export interface ServiceManifest<ConfigureOptions, RemoveOptions = ConfigureOptions> {
+    id: string;
+    summary: string;
+    configureMutations: ServiceMutation<ConfigureOptions>[];
+    removeMutations?: ServiceMutation<RemoveOptions>[];
+    configure(context: ServiceExecutionContext<ConfigureOptions>, runOptions?: ServiceRunOptions): Promise<void>;
+    remove: (context: ServiceExecutionContext<RemoveOptions>, runOptions?: ServiceRunOptions) => Promise<boolean>;
+}
 export interface ServiceExecutionContext<Options> {
     fs: FileSystem;
+    env: CliEnvironment;
+    command: CommandContext;
     options: Options;
 }
 export interface MutationLogDetails {
@@ -71,52 +81,70 @@ export interface ServiceMutationOutcome {
     detail?: MutationDetail;
 }
 export type MutationEffect = "none" | "mkdir" | "copy" | "write" | "delete";
-export interface ServiceMutationHooks {
+export interface ServiceMutationObservers {
     onStart?(details: MutationLogDetails): void;
     onComplete?(details: MutationLogDetails, outcome: ServiceMutationOutcome): void;
     onError?(details: MutationLogDetails, error: unknown): void;
 }
 export declare function ensureDirectory<Options>(config: {
     path: ValueResolver<Options, string>;
-    label?: string;
+    label?: ValueResolver<Options, string | undefined>;
 }): ServiceMutation<Options>;
 export declare function createBackupMutation<Options>(config: {
     target: ValueResolver<Options, string>;
     timestamp?: ValueResolver<Options, (() => string) | undefined>;
-    label?: string;
+    label?: ValueResolver<Options, string | undefined>;
 }): ServiceMutation<Options>;
 export declare function writeTemplateMutation<Options>(config: {
     target: ValueResolver<Options, string>;
     templateId: string;
     context?: ValueResolver<Options, JsonObject | undefined>;
-    label?: string;
+    label?: ValueResolver<Options, string | undefined>;
 }): ServiceMutation<Options>;
 export declare function jsonMergeMutation<Options>(config: {
     target: ValueResolver<Options, string>;
     value: ValueResolver<Options, JsonObject>;
-    label?: string;
+    label?: ValueResolver<Options, string | undefined>;
 }): ServiceMutation<Options>;
 export declare function jsonPruneMutation<Options>(config: {
     target: ValueResolver<Options, string>;
     shape: ValueResolver<Options, JsonObject>;
-    label?: string;
+    label?: ValueResolver<Options, string | undefined>;
+}): ServiceMutation<Options>;
+export declare function tomlMergeMutation<Options>(config: {
+    target: ValueResolver<Options, string>;
+    value: ValueResolver<Options, TomlTable>;
+    label?: ValueResolver<Options, string | undefined>;
+}): ServiceMutation<Options>;
+export declare function tomlPruneMutation<Options>(config: {
+    target: ValueResolver<Options, string>;
+    prune: (document: TomlTable, context: MutationContext<Options>) => {
+        changed: boolean;
+        result: TomlTable | null;
+    };
+    label?: ValueResolver<Options, string | undefined>;
+}): ServiceMutation<Options>;
+export declare function tomlTemplateMergeMutation<Options>(config: {
+    target: ValueResolver<Options, string>;
+    templateId: string;
+    context?: ValueResolver<Options, JsonObject | undefined>;
+    label?: ValueResolver<Options, string | undefined>;
 }): ServiceMutation<Options>;
 export declare function removePatternMutation<Options>(config: {
     target: ValueResolver<Options, string>;
     pattern: RegExp;
     replacement?: string | ((match: string, context: MutationContext<Options>) => string);
-    label?: string;
+    label?: ValueResolver<Options, string | undefined>;
 }): ServiceMutation<Options>;
 export declare function removeFileMutation<Options>(config: {
     target: ValueResolver<Options, string>;
     whenEmpty?: boolean;
     whenContentMatches?: RegExp;
-    label?: string;
+    label?: ValueResolver<Options, string | undefined>;
 }): ServiceMutation<Options>;
-export declare function runServiceConfigure<ConfigureOptions, RemoveOptions = ConfigureOptions>(manifest: ServiceManifest<ConfigureOptions, RemoveOptions>, context: ServiceExecutionContext<ConfigureOptions>, runOptions?: ServiceRunOptions): Promise<void>;
-export declare function runServiceRemove<ConfigureOptions, RemoveOptions = ConfigureOptions>(manifest: ServiceManifest<ConfigureOptions, RemoveOptions>, context: ServiceExecutionContext<RemoveOptions>, runOptions?: ServiceRunOptions): Promise<boolean>;
+export declare function createServiceManifest<ConfigureOptions, RemoveOptions = ConfigureOptions>(definition: ServiceManifestDefinition<ConfigureOptions, RemoveOptions>): ServiceManifest<ConfigureOptions, RemoveOptions>;
 export interface ServiceRunOptions {
-    hooks?: ServiceMutationHooks;
+    observers?: ServiceMutationObservers;
 }
 export type ServiceMutationKind = ServiceMutation<unknown>["kind"];
 export {};

package/dist/services/service-manifest.js

@@ -1,6 +1,8 @@
+import path from "node:path";
 import { createBackup } from "../utils/backup.js";
 import { renderTemplate } from "../utils/templates.js";
 import { deepMergeJson, isJsonObject, pruneJsonByShape } from "../utils/json.js";
+import { parseTomlDocument, serializeTomlDocument, mergeTomlTables } from "../utils/toml.js";
 export function ensureDirectory(config) {
     return {
         kind: "ensureDirectory",
@@ -31,7 +33,13 @@ export function jsonMergeMutation(config) {
         target: config.target,
         label: config.label,
         async transform({ content, context }) {
-            const current = parseJson(content);
+            const rawTarget = resolveValue(config.target, context);
+            const targetPath = expandHomeShortcut(rawTarget, context.env);
+            const current = await parseJsonWithRecovery({
+                content,
+                fs: context.fs,
+                targetPath
+            });
             const desired = resolveValue(config.value, context);
             const merged = deepMergeJson(current, desired);
             const serialized = serializeJson(merged);
@@ -68,6 +76,89 @@ export function jsonPruneMutation(config) {
         }
     };
 }
+export function tomlMergeMutation(config) {
+    return {
+        kind: "transformFile",
+        target: config.target,
+        label: config.label,
+        async transform({ content, context }) {
+            const rawTarget = resolveValue(config.target, context);
+            const targetPath = expandHomeShortcut(rawTarget, context.env);
+            const current = await parseTomlWithRecovery({
+                content,
+                fs: context.fs,
+                targetPath
+            });
+            const desired = resolveValue(config.value, context);
+            const merged = mergeTomlTables(current, desired);
+            const serialized = serializeTomlDocument(merged);
+            const previous = content ?? "";
+            return {
+                content: serialized,
+                changed: serialized !== previous
+            };
+        }
+    };
+}
+export function tomlPruneMutation(config) {
+    return {
+        kind: "transformFile",
+        target: config.target,
+        label: config.label,
+        async transform({ content, context }) {
+            if (content == null) {
+                return { content: null, changed: false };
+            }
+            let document;
+            try {
+                document = parseTomlDocument(content);
+            }
+            catch {
+                return { content, changed: false };
+            }
+            const outcome = config.prune(document, context);
+            if (!outcome.changed) {
+                return { content, changed: false };
+            }
+            if (!outcome.result || Object.keys(outcome.result).length === 0) {
+                return { content: null, changed: true };
+            }
+            const serialized = serializeTomlDocument(outcome.result);
+            return {
+                content: serialized,
+                changed: serialized !== content
+            };
+        }
+    };
+}
+export function tomlTemplateMergeMutation(config) {
+    return {
+        kind: "transformFile",
+        target: config.target,
+        label: config.label,
+        async transform({ content, context }) {
+            const rawTarget = resolveValue(config.target, context);
+            const targetPath = expandHomeShortcut(rawTarget, context.env);
+            const current = await parseTomlWithRecovery({
+                content,
+                fs: context.fs,
+                targetPath
+            });
+            const templateContext = config.context
+                ? resolveValue(config.context, context)
+                : undefined;
+            const rendered = await renderTemplate(config.templateId, templateContext ?? {});
+            const templateDocument = parseTomlDocument(rendered);
+            const merged = mergeTomlTables(current, templateDocument);
+            const serialized = serializeTomlDocument(merged);
+            const previous = content ?? "";
+            return {
+                content: serialized,
+                changed: serialized !== previous
+            };
+        }
+    };
+}
 export function removePatternMutation(config) {
     return {
         kind: "transformFile",
@@ -102,145 +193,165 @@ export function removeFileMutation(config) {
         label: config.label
     };
 }
-export async function runServiceConfigure(manifest, context, runOptions) {
-    await runMutations(manifest.configure, context, {
-        trackChanges: false,
-        hooks: runOptions?.hooks,
-        manifestId: manifest.id
-    });
-}
-export async function runServiceRemove(manifest, context, runOptions) {
-    return runMutations(manifest.remove ?? [], context, {
-        trackChanges: true,
-        hooks: runOptions?.hooks,
-        manifestId: manifest.id
-    });
+export function createServiceManifest(definition) {
+    const configureMutations = definition.configure;
+    const removeMutations = definition.remove;
+    return {
+        id: definition.id,
+        summary: definition.summary,
+        configureMutations,
+        removeMutations,
+        async configure(context, runOptions) {
+            await runMutations(configureMutations, context, {
+                trackChanges: false,
+                observers: runOptions?.observers,
+                manifestId: definition.id
+            });
+        },
+        async remove(context, runOptions) {
+            if (!removeMutations) {
+                return false;
+            }
+            return runMutations(removeMutations, context, {
+                trackChanges: true,
+                observers: runOptions?.observers,
+                manifestId: definition.id
+            });
+        }
+    };
 }
 async function runMutations(mutations, context, options) {
     let touched = false;
     for (const mutation of mutations) {
-        const changed = await applyMutation(mutation, context, options.manifestId, options.hooks);
+        const changed = await applyMutation(mutation, context, options.manifestId, options.observers);
         if (options.trackChanges && changed) {
             touched = true;
         }
     }
     return touched;
 }
-async function applyMutation(mutation, context, manifestId, hooks) {
+async function applyMutation(mutation, context, manifestId, observers) {
     switch (mutation.kind) {
         case "ensureDirectory": {
-            const targetPath = resolveValue(mutation.path, mutationContext(context));
-            const details = createMutationDetails(mutation, manifestId, targetPath);
-            hooks?.onStart?.(details);
+            const targetPath = resolvePath(mutation.path, context);
+            const details = createMutationDetails(mutation, manifestId, targetPath, context);
+            observers?.onStart?.(details);
             try {
                 const existed = await pathExists(context.fs, targetPath);
                 await context.fs.mkdir(targetPath, { recursive: true });
-                hooks?.onComplete?.(details, {
+                observers?.onComplete?.(details, {
                     changed: !existed,
                     effect: "mkdir",
                     detail: existed ? "noop" : "create"
                 });
+                flushCommandDryRun(context);
                 return !existed;
             }
             catch (error) {
-                hooks?.onError?.(details, error);
+                observers?.onError?.(details, error);
                 throw error;
             }
         }
         case "createBackup": {
-            const targetPath = resolveValue(mutation.target, mutationContext(context));
+            const targetPath = resolvePath(mutation.target, context);
             const timestamp = mutation.timestamp
                 ? resolveValue(mutation.timestamp, mutationContext(context))
                 : undefined;
-            const details = createMutationDetails(mutation, manifestId, targetPath);
-            hooks?.onStart?.(details);
+            const details = createMutationDetails(mutation, manifestId, targetPath, context);
+            observers?.onStart?.(details);
             try {
                 const backupPath = await createBackup(context.fs, targetPath, timestamp);
-                hooks?.onComplete?.(details, {
+                observers?.onComplete?.(details, {
                     changed: backupPath != null,
                     effect: backupPath ? "copy" : "none",
                     detail: backupPath ? "backup" : "noop"
                 });
+                flushCommandDryRun(context);
             }
             catch (error) {
-                hooks?.onError?.(details, error);
+                observers?.onError?.(details, error);
                 throw error;
             }
             return false;
         }
         case "writeTemplate": {
-            const targetPath = resolveValue(mutation.target, mutationContext(context));
+            const targetPath = resolvePath(mutation.target, context);
             const renderContext = mutation.context
                 ? resolveValue(mutation.context, mutationContext(context))
                 : undefined;
             const rendered = await renderTemplate(mutation.templateId, renderContext ?? {});
-            const details = createMutationDetails(mutation, manifestId, targetPath);
-            hooks?.onStart?.(details);
+            const details = createMutationDetails(mutation, manifestId, targetPath, context);
+            observers?.onStart?.(details);
             try {
                 const existed = await pathExists(context.fs, targetPath);
                 await context.fs.writeFile(targetPath, rendered, { encoding: "utf8" });
-                hooks?.onComplete?.(details, {
+                observers?.onComplete?.(details, {
                     changed: true,
                     effect: "write",
                     detail: existed ? "update" : "create"
                 });
+                flushCommandDryRun(context);
             }
             catch (error) {
-                hooks?.onError?.(details, error);
+                observers?.onError?.(details, error);
                 throw error;
             }
             return true;
         }
         case "removeFile": {
-            const targetPath = resolveValue(mutation.target, mutationContext(context));
-            const details = createMutationDetails(mutation, manifestId, targetPath);
-            hooks?.onStart?.(details);
+            const targetPath = resolvePath(mutation.target, context);
+            const details = createMutationDetails(mutation, manifestId, targetPath, context);
+            observers?.onStart?.(details);
             try {
                 const raw = await context.fs.readFile(targetPath, "utf8");
                 const trimmed = raw.trim();
                 if (mutation.whenContentMatches &&
                     !mutation.whenContentMatches.test(trimmed)) {
-                    hooks?.onComplete?.(details, {
+                    observers?.onComplete?.(details, {
                         changed: false,
                         effect: "none",
                         detail: "noop"
                     });
+                    flushCommandDryRun(context);
                     return false;
                 }
                 if (mutation.whenEmpty && trimmed.length > 0) {
-                    hooks?.onComplete?.(details, {
+                    observers?.onComplete?.(details, {
                         changed: false,
                         effect: "none",
                         detail: "noop"
                     });
+                    flushCommandDryRun(context);
                     return false;
                 }
                 await context.fs.unlink(targetPath);
-                hooks?.onComplete?.(details, {
+                observers?.onComplete?.(details, {
                     changed: true,
                     effect: "delete",
                     detail: "delete"
                 });
+                flushCommandDryRun(context);
                 return true;
             }
             catch (error) {
                 if (isNotFound(error)) {
-                    hooks?.onComplete?.(details, {
+                    observers?.onComplete?.(details, {
                         changed: false,
                         effect: "none",
                         detail: "noop"
                     });
+                    flushCommandDryRun(context);
                     return false;
                 }
-                hooks?.onError?.(details, error);
+                observers?.onError?.(details, error);
                 throw error;
             }
         }
         case "transformFile": {
-            const targetPath = resolveValue(mutation.target, mutationContext(context));
+            const targetPath = resolvePath(mutation.target, context);
             const current = await readFileIfExists(context.fs, targetPath);
-            const details = createMutationDetails(mutation, manifestId, targetPath);
-            hooks?.onStart?.(details);
+            const details = createMutationDetails(mutation, manifestId, targetPath, context);
+            observers?.onStart?.(details);
             try {
                 const result = await mutation.transform({
                     content: current,
@@ -252,11 +363,12 @@ async function applyMutation(mutation, context, manifestId, hooks) {
                     previousContent: current,
                     result
                 });
-                hooks?.onComplete?.(details, transformOutcome);
+                observers?.onComplete?.(details, transformOutcome);
+                flushCommandDryRun(context);
                 return transformOutcome.changed;
             }
             catch (error) {
-                hooks?.onError?.(details, error);
+                observers?.onError?.(details, error);
                 throw error;
             }
         }
@@ -269,40 +381,81 @@ async function applyMutation(mutation, context, manifestId, hooks) {
 function mutationContext(context) {
     return {
         fs: context.fs,
-        options: context.options
+        options: context.options,
+        env: context.env
     };
 }
-function createMutationDetails(mutation, manifestId, targetPath) {
-    const subject = (() => {
-        switch (mutation.kind) {
-            case "ensureDirectory":
-                return mutation.label ?? "Ensure directory";
-            case "createBackup":
-                return mutation.label ?? "Create backup";
-            case "writeTemplate":
-                return (mutation.label ??
-                    `Write template ${mutation.templateId}`);
-            case "removeFile":
-                return mutation.label ?? "Remove file";
-            case "transformFile":
-                return mutation.label ?? "Transform file";
-            default:
-                return "Operation";
-        }
-    })();
+function createMutationDetails(mutation, manifestId, targetPath, context) {
+    const customLabel = mutation.label != null
+        ? resolveValue(mutation.label, mutationContext(context))
+        : undefined;
+    const label = customLabel ?? describeMutationOperation(mutation.kind, targetPath);
     return {
         manifestId,
         kind: mutation.kind,
-        label: subject,
+        label,
         targetPath
     };
 }
+function describeMutationOperation(kind, targetPath) {
+    const displayPath = targetPath ?? "target";
+    switch (kind) {
+        case "ensureDirectory":
+            return `Ensure directory ${displayPath}`;
+        case "createBackup":
+            return `Create backup ${displayPath}`;
+        case "writeTemplate":
+            return `Write file ${displayPath}`;
+        case "removeFile":
+            return `Remove file ${displayPath}`;
+        case "transformFile":
+            return `Transform file ${displayPath}`;
+        default:
+            return "Operation";
+    }
+}
 function resolveValue(resolver, context) {
     if (typeof resolver === "function") {
         return resolver(context);
     }
     return resolver;
 }
+function resolvePath(resolver, context) {
+    const raw = resolveValue(resolver, mutationContext(context));
+    return expandHomeShortcut(raw, context.env);
+}
+function flushCommandDryRun(context) {
+    context.command.flushDryRun({ emitIfEmpty: false });
+}
+function expandHomeShortcut(targetPath, env) {
+    if (!targetPath?.startsWith("~")) {
+        return targetPath;
+    }
+    if (targetPath.startsWith("~./")) {
+        targetPath = `~/.${targetPath.slice(3)}`;
+    }
+    const homeDir = env?.homeDir ?? process.env.HOME ?? process.env.USERPROFILE;
+    if (!homeDir) {
+        return targetPath;
+    }
+    let remainder = targetPath.slice(1);
+    if (remainder.startsWith("/")) {
+        remainder = remainder.slice(1);
+    }
+    else if (remainder.startsWith("\\")) {
+        remainder = remainder.slice(1);
+    }
+    else if (remainder.startsWith(".")) {
+        remainder = remainder.slice(1);
+        if (remainder.startsWith("/")) {
+            remainder = remainder.slice(1);
+        }
+        else if (remainder.startsWith("\\")) {
+            remainder = remainder.slice(1);
+        }
+    }
+    return remainder.length === 0 ? homeDir : path.join(homeDir, remainder);
+}
 function parseJson(content) {
     if (content == null) {
         return {};
@@ -313,6 +466,50 @@ function parseJson(content) {
     }
     return parsed;
 }
+async function parseJsonWithRecovery(input) {
+    try {
+        return parseJson(input.content);
+    }
+    catch {
+        await backupInvalidJsonDocument(input);
+        return {};
+    }
+}
+async function parseTomlWithRecovery(input) {
+    if (input.content == null) {
+        return {};
+    }
+    try {
+        return parseTomlDocument(input.content);
+    }
+    catch {
+        await backupInvalidTomlDocument(input);
+        return {};
+    }
+}
+async function backupInvalidJsonDocument(input) {
+    if (input.content == null) {
+        return;
+    }
+    const backupPath = createInvalidDocumentBackupPath(input.targetPath);
+    await input.fs.writeFile(backupPath, input.content, { encoding: "utf8" });
+}
+async function backupInvalidTomlDocument(input) {
+    if (input.content == null) {
+        return;
+    }
+    const backupPath = createInvalidDocumentBackupPath(input.targetPath);
+    await input.fs.writeFile(backupPath, input.content, { encoding: "utf8" });
+}
+function createInvalidDocumentBackupPath(targetPath) {
+    return `${targetPath}.invalid-${createTimestamp()}.json`;
+}
+function createTimestamp() {
+    return new Date()
+        .toISOString()
+        .replaceAll(":", "-")
+        .replaceAll(".", "-");
+}
 function serializeJson(value) {
     return `${JSON.stringify(value, null, 2)}\n`;
 }