@deterministic-code/migraters 0.0.2 → 0.0.3

package/csharp/MigrateDown.cs

@@ -0,0 +1,147 @@
+// Rolls back the most recently applied migration (one step). DESTRUCTIVE: refuses to proceed unless the operator types confirm on stdin, or passes --confirm.
+
+namespace Deterministic.MigrateRunner;
+
+internal sealed class MigrateDown(ISqlDialectFactory dialects, IConnectionResolver connections)
+    : IMigrateCommand
+{
+    private static readonly string HelpText = HelpTemplates.Read("down");
+
+    public string Name => "down";
+
+    public async Task<int> RunAsync(string[] args)
+    {
+        if (!TryParse(args, out var provider, out var migratePath, out var connection, out var confirm, out var showHelp, out var error))
+            return showHelp ? WriteHelp() : Fail(error);
+
+        if (!MigrateCli.TryResolveProvider(dialects, connections, provider, connection, out var dialect, out connection, out error))
+            return Fail(error);
+
+        if (dialect.PrerequisiteError(connection) is { } prerequisite)
+            return Fail(prerequisite);
+
+        if (!ConfirmOrAbort(dialect.Name, confirm))
+            return 2;
+
+        try
+        {
+            var name = await new Migrater(dialect).Down(new DownArg(connection, migratePath)).ConfigureAwait(false);
+            Console.WriteLine(
+                name is null
+                    ? HelpTemplates.Message("status/no-rollback")
+                    : HelpTemplates.Message("status/rolled-back", new Dictionary<string, string> { ["name"] = name })
+            );
+            return 0;
+        }
+        catch (Exception ex)
+        {
+            return Fail($"migrate-down failed: {ex.Message}", 1);
+        }
+    }
+
+    private static bool ConfirmOrAbort(string dialect, bool confirm)
+    {
+        Console.Error.Write(
+            HelpTemplates.Message(
+                "down/destructive-header",
+                new Dictionary<string, string> { ["dialect"] = dialect }
+            )
+        );
+        if (confirm)
+            return true;
+        if (Console.IsInputRedirected)
+        {
+            Console.Error.WriteLine(HelpTemplates.Message("down/confirm-tty-required"));
+            return false;
+        }
+        Console.Error.Write(HelpTemplates.Message("down/confirm-prompt"));
+        Console.Error.Flush();
+        var line = Console.In.ReadLine()?.Trim();
+        if (line == "confirm")
+            return true;
+        Console.Error.WriteLine(
+            line is null
+                ? HelpTemplates.Message("down/confirm-stdin-failed")
+                : HelpTemplates.Message("down/confirm-token-mismatch")
+        );
+        return false;
+    }
+
+    private bool TryParse(
+        string[] args,
+        out string provider,
+        out string migratePath,
+        out string? connection,
+        out bool confirm,
+        out bool showHelp,
+        out string error
+    )
+    {
+        provider = string.Empty;
+        migratePath = string.Empty;
+        connection = null;
+        confirm = false;
+        showHelp = false;
+        error = string.Empty;
+        string? migrateRoot = null;
+
+        for (var i = 0; i < args.Length; i++)
+        {
+            var a = args[i];
+            if (a is "-h" or "--help")
+            {
+                showHelp = true;
+                return false;
+            }
+            if (MigrateCli.TryTakeFlag(args, ref i, a, "--provider", out var takenProvider))
+            {
+                provider = takenProvider;
+                continue;
+            }
+            if (MigrateCli.TryTakeFlag(args, ref i, a, "--connection", out var c))
+            {
+                connection = c;
+                continue;
+            }
+            if (a == "--confirm")
+            {
+                confirm = true;
+                continue;
+            }
+            if (MigrateCli.TryTakeFlag(args, ref i, a, "--migrations-path", out var takenPath)
+                || MigrateCli.TryTakeFlag(args, ref i, a, "--migrate-path", out takenPath))
+            {
+                migratePath = takenPath;
+                continue;
+            }
+            if (MigrateCli.TryTakeFlag(args, ref i, a, "--migrations-root", out var takenRoot)
+                || MigrateCli.TryTakeFlag(args, ref i, a, "--migrate-root", out takenRoot))
+            {
+                migrateRoot = takenRoot;
+                continue;
+            }
+
+            error = MigrateCli.ParseArgError(a, MigrateCli.IsValueFlag(a) && i + 1 >= args.Length);
+            return false;
+        }
+
+        if (string.IsNullOrEmpty(provider))
+            return MigrateCli.MissingProvider(out error);
+        migratePath = MigrateCli.MigratePath(provider, migratePath, migrateRoot);
+        return true;
+    }
+
+    private static int WriteHelp()
+    {
+        Console.Error.Write(HelpText);
+        return 0;
+    }
+
+    private static int Fail(string error, int code = 2)
+    {
+        Console.Error.WriteLine(error);
+        if (code == 2)
+            Console.Error.Write(HelpText);
+        return code;
+    }
+}

package/csharp/MigrateRunner.Core.csproj

@@ -0,0 +1,66 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net9.0</TargetFramework>
+    <RollForward>LatestMajor</RollForward>
+    <RootNamespace>Deterministic.MigrateRunner</RootNamespace>
+    <AssemblyName>MigrateCore</AssemblyName>
+    <LangVersion>latest</LangVersion>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <IsPackable>false</IsPackable>
+    <NoWarn>$(NoWarn);CA1031;CA1303;CA1812;CA1848;CA2007</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <InternalsVisibleTo Include="MigrateRunner" />
+    <InternalsVisibleTo Include="MigrateRunner.Tests" />
+    <InternalsVisibleTo Include="MigrateSqlite" />
+    <InternalsVisibleTo Include="MigratePostgres" />
+    <InternalsVisibleTo Include="MigrateMysql" />
+    <InternalsVisibleTo Include="MigrateSqlServer" />
+    <InternalsVisibleTo Include="MigrateOracle" />
+    <Compile Remove="Program.cs" />
+    <Compile Remove="MigrateRunner.Tests/**" />
+    <Compile Remove="MigrateInit/**" />
+    <Compile Remove="Dialects/**" />
+    <Content Remove="MigrateRunner.Tests/**" />
+    <Content Remove="MigrateInit/**" />
+    <Content Remove="Dialects/**" />
+    <None Remove="MigrateRunner.Tests/**" />
+    <None Remove="MigrateInit/**" />
+    <None Remove="Dialects/**" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Content
+      Include="..\cli.yaml"
+      Link="cli.yaml"
+      CopyToOutputDirectory="PreserveNewest"
+    />
+    <Content
+      Include="..\shared\templates\sql\**\*.sql"
+      Link="templates\sql\%(RecursiveDir)%(Filename)%(Extension)"
+      CopyToOutputDirectory="PreserveNewest"
+    />
+    <Content
+      Include="..\shared\templates\help\*.txt"
+      Link="templates\help\%(Filename)%(Extension)"
+      CopyToOutputDirectory="PreserveNewest"
+    />
+    <Content
+      Include="..\shared\templates\messages\**\*.txt"
+      Link="templates\messages\%(RecursiveDir)%(Filename)%(Extension)"
+      CopyToOutputDirectory="PreserveNewest"
+    />
+    <Content
+      Include="..\shared\templates\scaffold\*.sql"
+      Link="templates\scaffold\%(Filename)%(Extension)"
+      CopyToOutputDirectory="PreserveNewest"
+    />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="DotNetEnv" Version="3.2.0" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="9.0.0" />
+  </ItemGroup>
+</Project>

package/csharp/MigrateRunner.csproj

@@ -0,0 +1,63 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <RollForward>LatestMajor</RollForward>
+    <RootNamespace>Deterministic.MigrateRunner</RootNamespace>
+    <AssemblyName>MigrateRunner</AssemblyName>
+    <LangVersion>latest</LangVersion>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <IsPackable>false</IsPackable>
+    <UseAppHost>true</UseAppHost>
+    <NoWarn>$(NoWarn);CA1031;CA1303;CA1812;CA1848;CA2007</NoWarn>
+  </PropertyGroup>
+
+  <Import Project="dialects.props" Condition="Exists('dialects.props')" />
+
+  <ItemGroup>
+    <Compile Remove="**/*.cs" />
+    <Compile Include="Program.cs" />
+    <Compile Include="GlobalUsings.cs" />
+    <Compile Remove="MigrateRunner.Tests/**" />
+    <Compile Remove="MigrateInit/**" />
+    <Compile Remove="Dialects/**" />
+  </ItemGroup>
+
+  <PropertyGroup>
+    <MigrateVerbNames>migrate-setup;migrate-up;migrate-down;migrate-create</MigrateVerbNames>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="MigrateRunner.Core.csproj" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="9.0.0" />
+  </ItemGroup>
+
+  <Target Name="CopyMigrateCommandHosts" AfterTargets="CopyFilesToOutputDirectory">
+    <PropertyGroup>
+      <_MigrateExeExt Condition="$([MSBuild]::IsOSPlatform('Windows'))">.exe</_MigrateExeExt>
+    </PropertyGroup>
+    <ItemGroup>
+      <_MigrateVerb Include="$(MigrateVerbNames)" />
+    </ItemGroup>
+    <Copy
+      SourceFiles="$(TargetDir)$(AssemblyName)$(_MigrateExeExt)"
+      DestinationFiles="$(TargetDir)%(_MigrateVerb.Identity)$(_MigrateExeExt)"
+      SkipUnchangedFiles="true"
+    />
+  </Target>
+
+  <Target Name="CopyMigrateCommandHostsOnPublish" AfterTargets="Publish">
+    <PropertyGroup>
+      <_MigrateExeExt Condition="$([MSBuild]::IsOSPlatform('Windows'))">.exe</_MigrateExeExt>
+    </PropertyGroup>
+    <ItemGroup>
+      <_MigrateVerb Include="$(MigrateVerbNames)" />
+    </ItemGroup>
+    <Copy
+      SourceFiles="$(PublishDir)$(AssemblyName)$(_MigrateExeExt)"
+      DestinationFiles="$(PublishDir)%(_MigrateVerb.Identity)$(_MigrateExeExt)"
+      SkipUnchangedFiles="true"
+    />
+  </Target>
+</Project>

package/csharp/MigrateRunnerServices.cs

@@ -0,0 +1,55 @@
+using System.Reflection;
+
+namespace Deterministic.MigrateRunner;
+
+internal static class MigrateRunnerServices
+{
+    public static IServiceCollection AddMigrateRunner(this IServiceCollection services)
+    {
+        foreach (var dialect in LoadDialects())
+            services.AddSingleton(dialect);
+        return services
+            .AddSingleton<ISqlDialectFactory, SqlDialectFactory>()
+            .AddSingleton<IConnectionResolver, ConnectionResolver>()
+            .AddSingleton<IMigrateCommand, MigrateSetup>()
+            .AddSingleton<IMigrateCommand, MigrateUp>()
+            .AddSingleton<IMigrateCommand, MigrateDown>()
+            .AddSingleton<IMigrateCommand, MigrateCreate>();
+    }
+
+    private static IEnumerable<ISqlDialect> LoadDialects()
+    {
+        var dir = AppContext.BaseDirectory;
+        foreach (var path in Directory.GetFiles(dir, "Migrate*.dll"))
+        {
+            var name = Path.GetFileNameWithoutExtension(path);
+            if (name is "MigrateCore" or "MigrateRunner" or "MigrateRunner.Tests")
+                continue;
+            Assembly.LoadFrom(path);
+        }
+
+        return AppDomain
+            .CurrentDomain.GetAssemblies()
+            .SelectMany(SafeTypes)
+            .Where(t => !t.ContainsGenericParameters)
+            .Select(t => t.GetField("Instance", BindingFlags.Public | BindingFlags.Static))
+            .Where(f =>
+                f is { IsStatic: true }
+                && !f.FieldType.ContainsGenericParameters
+                && typeof(ISqlDialect).IsAssignableFrom(f.FieldType)
+            )
+            .Select(f => (ISqlDialect)f!.GetValue(null)!);
+    }
+
+    private static IEnumerable<Type> SafeTypes(Assembly assembly)
+    {
+        try
+        {
+            return assembly.GetTypes();
+        }
+        catch (ReflectionTypeLoadException ex)
+        {
+            return ex.Types.OfType<Type>();
+        }
+    }
+}

package/csharp/MigrateSetup.cs

@@ -0,0 +1,145 @@
+// Idempotent CREATE TABLE IF NOT EXISTS migrates+migrate_logs via IMigrater.Setup.
+
+namespace Deterministic.MigrateRunner;
+
+internal sealed class MigrateSetup(ISqlDialectFactory dialects, IConnectionResolver connections)
+    : IMigrateCommand
+{
+    private static readonly string HelpText = HelpTemplates.Read("setup");
+
+    public string Name => "setup";
+
+    public async Task<int> RunAsync(string[] args)
+    {
+        if (!TryParse(args, out var provider, out var connection, out var migrationsPath, out var andUp, out var createDatabase, out var showHelp, out var error))
+            return showHelp ? WriteHelp() : Fail(error);
+
+        if (!MigrateCli.TryResolveProvider(dialects, connections, provider, connection, out var dialect, out connection, out error))
+            return Fail(error);
+
+        var resolvedMigrationsPath = migrationsPath ?? $"./sql/{dialect.Name}/migrations";
+        var migrater = new Migrater(dialect);
+
+        try
+        {
+            if (createDatabase)
+                await CreateDatabase.RunAsync(dialect, connection).ConfigureAwait(false);
+            await migrater.Setup(new SetupArg(connection, resolvedMigrationsPath)).ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            return Fail($"setup failed: {ex.Message}", 1);
+        }
+
+        Console.Write(
+            HelpTemplates.Message(
+                "setup-complete",
+                new Dictionary<string, string>
+                {
+                    ["dialect"] = dialect.Name,
+                    ["migrationsPath"] = resolvedMigrationsPath,
+                    ["createExample"] =
+                        $"  migrate-create --provider {dialect.Name} --name add_users",
+                    ["upExample"] =
+                        $"  migrate-up --provider {dialect.Name} --connection {connection}",
+                }
+            )
+        );
+        if (!andUp)
+            return 0;
+        try
+        {
+            var names = await migrater.Up(new UpArg(connection, resolvedMigrationsPath)).ConfigureAwait(false);
+            if (names.Count == 0)
+                Console.WriteLine(HelpTemplates.Message("status/no-pending"));
+            else
+            {
+                foreach (var name in names)
+                    Console.WriteLine(
+                        HelpTemplates.Message("status/applied", new Dictionary<string, string> { ["name"] = name })
+                    );
+                Console.WriteLine(HelpTemplates.Message("status/no-more-pending"));
+            }
+            return 0;
+        }
+        catch (Exception ex)
+        {
+            return Fail($"migrate-up failed: {ex.Message}", 1);
+        }
+    }
+
+    private bool TryParse(
+        string[] args,
+        out string provider,
+        out string? connection,
+        out string? migrationsPath,
+        out bool andUp,
+        out bool createDatabase,
+        out bool showHelp,
+        out string error
+    )
+    {
+        provider = string.Empty;
+        connection = null;
+        migrationsPath = null;
+        andUp = false;
+        createDatabase = false;
+        showHelp = false;
+        error = string.Empty;
+
+        for (var i = 0; i < args.Length; i++)
+        {
+            var a = args[i];
+            if (a is "-h" or "--help")
+            {
+                showHelp = true;
+                return false;
+            }
+            if (MigrateCli.TryTakeFlag(args, ref i, a, "--provider", out var takenProvider))
+            {
+                provider = takenProvider;
+                continue;
+            }
+            if (MigrateCli.TryTakeFlag(args, ref i, a, "--connection", out var takenConnection))
+            {
+                connection = takenConnection;
+                continue;
+            }
+            if (a == "--and-up")
+            {
+                andUp = true;
+                continue;
+            }
+            if (a == "--create-database")
+            {
+                createDatabase = true;
+                continue;
+            }
+            if (MigrateCli.TryTakeFlag(args, ref i, a, "--migrations-path", out var takenPath)
+                || MigrateCli.TryTakeFlag(args, ref i, a, "--migrate-path", out takenPath))
+            {
+                migrationsPath = takenPath;
+                continue;
+            }
+
+            error = MigrateCli.ParseArgError(a, MigrateCli.IsValueFlag(a) && i + 1 >= args.Length);
+            return false;
+        }
+
+        return !string.IsNullOrEmpty(provider) || MigrateCli.MissingProvider(out error);
+    }
+
+    private static int WriteHelp()
+    {
+        Console.Error.Write(HelpText);
+        return 0;
+    }
+
+    private static int Fail(string error, int code = 2)
+    {
+        Console.Error.WriteLine(error);
+        if (code == 2)
+            Console.Error.Write(HelpText);
+        return code;
+    }
+}

package/csharp/MigrateUp.cs

@@ -0,0 +1,122 @@
+// Default: applies ALL pending migrations in sequence, each in its own transaction. Pass --one to apply only the next pending migration (legacy one-shot behavior; useful when wrapping in an external loop or when you want to inspect state between steps).
+
+namespace Deterministic.MigrateRunner;
+
+internal sealed class MigrateUp(ISqlDialectFactory dialects, IConnectionResolver connections)
+    : IMigrateCommand
+{
+    private static readonly string HelpText = HelpTemplates.Read("up");
+
+    public string Name => "up";
+
+    public async Task<int> RunAsync(string[] args)
+    {
+        if (!TryParse(args, out var provider, out var migratePath, out var connection, out var one, out var showHelp, out var error))
+            return showHelp ? WriteHelp() : Fail(error);
+
+        if (!MigrateCli.TryResolveProvider(dialects, connections, provider, connection, out var dialect, out connection, out error))
+            return Fail(error);
+
+        if (dialect.PrerequisiteError(connection) is { } prerequisite)
+            return Fail(prerequisite);
+
+        try
+        {
+            var names = await new Migrater(dialect).Up(new UpArg(connection, migratePath, one)).ConfigureAwait(false);
+            if (names.Count == 0)
+                Console.WriteLine(HelpTemplates.Message("status/no-pending"));
+            else
+            {
+                foreach (var name in names)
+                    Console.WriteLine(
+                        HelpTemplates.Message("status/applied", new Dictionary<string, string> { ["name"] = name })
+                    );
+                if (!one)
+                    Console.WriteLine(HelpTemplates.Message("status/no-more-pending"));
+            }
+            return 0;
+        }
+        catch (Exception ex)
+        {
+            return Fail($"migrate-up failed: {ex.Message}", 1);
+        }
+    }
+
+    private bool TryParse(
+        string[] args,
+        out string provider,
+        out string migratePath,
+        out string? connection,
+        out bool one,
+        out bool showHelp,
+        out string error
+    )
+    {
+        provider = string.Empty;
+        migratePath = string.Empty;
+        connection = null;
+        one = false;
+        showHelp = false;
+        error = string.Empty;
+        string? migrateRoot = null;
+
+        for (var i = 0; i < args.Length; i++)
+        {
+            var a = args[i];
+            if (a is "-h" or "--help")
+            {
+                showHelp = true;
+                return false;
+            }
+            if (a == "--one")
+            {
+                one = true;
+                continue;
+            }
+            if (MigrateCli.TryTakeFlag(args, ref i, a, "--provider", out var takenProvider))
+            {
+                provider = takenProvider;
+                continue;
+            }
+            if (MigrateCli.TryTakeFlag(args, ref i, a, "--connection", out var c))
+            {
+                connection = c;
+                continue;
+            }
+            if (MigrateCli.TryTakeFlag(args, ref i, a, "--migrations-path", out var takenPath)
+                || MigrateCli.TryTakeFlag(args, ref i, a, "--migrate-path", out takenPath))
+            {
+                migratePath = takenPath;
+                continue;
+            }
+            if (MigrateCli.TryTakeFlag(args, ref i, a, "--migrations-root", out var takenRoot)
+                || MigrateCli.TryTakeFlag(args, ref i, a, "--migrate-root", out takenRoot))
+            {
+                migrateRoot = takenRoot;
+                continue;
+            }
+
+            error = MigrateCli.ParseArgError(a, MigrateCli.IsValueFlag(a) && i + 1 >= args.Length);
+            return false;
+        }
+
+        if (string.IsNullOrEmpty(provider))
+            return MigrateCli.MissingProvider(out error);
+        migratePath = MigrateCli.MigratePath(provider, migratePath, migrateRoot);
+        return true;
+    }
+
+    private static int WriteHelp()
+    {
+        Console.Error.Write(HelpText);
+        return 0;
+    }
+
+    private static int Fail(string error, int code = 2)
+    {
+        Console.Error.WriteLine(error);
+        if (code == 2)
+            Console.Error.Write(HelpText);
+        return code;
+    }
+}

package/csharp/Program.cs

@@ -0,0 +1,40 @@
+// One project, four verbs. `dotnet build` / `dotnet publish` copies the apphost to
+// migrate-setup[.exe], migrate-up[.exe], … so the invocation matches the ts/rust bins.
+// `dotnet MigrateRunner.dll migrate-up …` still works (verb from argv).
+
+// NoClobber: real env vars win over .env, matching the ts/rust lanes.
+DotNetEnv.Env.NoClobber().Load();
+
+var services = new ServiceCollection();
+services.AddMigrateRunner();
+await using var provider = services.BuildServiceProvider();
+
+var hostVerb = MigrateCli.VerbFromHost();
+if (hostVerb is not null)
+{
+    var hosted = provider.GetServices<IMigrateCommand>().First(c => c.Name == hostVerb);
+    return await hosted.RunAsync(args).ConfigureAwait(false);
+}
+
+if (args.Length == 0)
+    return PrintUsage(2);
+
+var sub = args[0];
+if (sub is "-h" or "--help")
+    return PrintUsage(0);
+
+sub = MigrateCli.NormalizeVerb(sub);
+var rest = args.Skip(1).ToArray();
+var command = provider.GetServices<IMigrateCommand>().FirstOrDefault(c => c.Name == sub);
+if (command is null)
+    return PrintUsage(2, $"Unknown subcommand: {sub}");
+
+return await command.RunAsync(rest).ConfigureAwait(false);
+
+static int PrintUsage(int code, string? error = null)
+{
+    if (error is not null)
+        Console.Error.WriteLine(error);
+    Console.Error.Write(HelpTemplates.ProgramUsage());
+    return code;
+}

package/{dist → orchestrator/dist}/cli-spec.d.ts

@@ -11,6 +11,7 @@ export type CliCommand = {
 export type CliSpec = {
     command: string;
     providers: string[];
+    languages: string[];
     provider_aliases: Record<string, string>;
     aliases: Record<string, string>;
     env_var_list_separator: string;
@@ -21,4 +22,3 @@ export declare const cliYamlPath: () => string;
 export declare const cliSpec: CliSpec;
 export declare const migrateCommand: (verb: MigrateVerb) => string;
 export declare const usageLine: (verb: MigrateVerb) => string;
-export declare const programUsageText: () => string;

package/{dist → orchestrator/dist}/cli-spec.js

@@ -3,9 +3,13 @@ import { readFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parse } from 'yaml';
+import { packageRootFromModule } from "./repo.js";
 export const cliYamlPath = () => {
     const here = dirname(fileURLToPath(import.meta.url));
+    const root = packageRootFromModule(import.meta.url);
     const candidates = [
+        join(root, 'cli.yaml'),
+        join(here, 'cli.yaml'),
         join(here, '..', 'cli.yaml'),
         join(here, '..', '..', 'cli.yaml'),
         join(process.cwd(), 'cli.yaml'),
@@ -19,8 +23,13 @@ export const cliYamlPath = () => {
 export const cliSpec = parse(await readFile(cliYamlPath(), 'utf8'));
 export const migrateCommand = (verb) => cliSpec.command.replace('{verb}', verb);
 const providers = cliSpec.providers.join('|');
+const languages = (cliSpec.languages ?? []).join('|');
 const argUsage = (arg) => {
-    const ph = arg.placeholder === 'providers' ? providers : arg.placeholder;
+    const ph = arg.placeholder === 'providers'
+        ? providers
+        : arg.placeholder === 'languages'
+            ? languages
+            : arg.placeholder;
     const body = ph ? `${arg.flag} <${ph}>` : arg.flag;
     return arg.required ? body : `[${body}]`;
 };
@@ -30,4 +39,3 @@ export const usageLine = (verb) => {
         throw new Error(`cli.yaml: missing command ${verb}`);
     return `Usage: ${migrateCommand(verb)} ${command.args.map(argUsage).join(' ')}`;
 };
-export const programUsageText = () => `${cliSpec.commands.map((c) => usageLine(c.verb)).join('\n')}\n`;