@wictorwilen/cocogen 1.0.0 → 1.0.11

package/dist/init/templates/dotnet/Program.commandline.cs.ejs

@@ -1,24 +1,17 @@
-using Azure.Core;
+// Connector CLI for provisioning, ingestion, and deletion.
 using Azure.Identity;
 using Microsoft.Extensions.Configuration;
 <% if (graphApiVersion === "beta") { -%>
 using Microsoft.Graph.Beta;
-using Microsoft.Graph.Beta.Models.ExternalConnectors;
-using Microsoft.Graph.Beta.Models.ODataErrors;
 <% } else { -%>
 using Microsoft.Graph;
-using Microsoft.Graph.Models.ExternalConnectors;
-using Microsoft.Graph.Models.ODataErrors;
 <% } -%>
-using Microsoft.Kiota.Abstractions;
-using Microsoft.Kiota.Abstractions.Serialization;
 using System.CommandLine;
-using System.Net.Http.Headers;
-using System.Text;
-using System.Text.Json;
+using System.Threading;
 
+using <%= namespaceName %>.Core;
 using <%= namespaceName %>.Datasource;
-using <%= namespaceName %>.Schema;
+using <%= schemaNamespace %>;
 
 var configuration = new ConfigurationBuilder()
     .SetBasePath(Directory.GetCurrentDirectory())
@@ -27,6 +20,33 @@ var configuration = new ConfigurationBuilder()
     .AddEnvironmentVariables()
     .Build();
 
+bool UseColor() => string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable("NO_COLOR"));
+
+void PrintBanner()
+{
+    var title = "✨ 🥥 <%= itemTypeName %> connector CLI 🥥 ✨";
+    var subtitle = "Provision • Ingest • Delete";
+    if (UseColor())
+    {
+        var original = Console.ForegroundColor;
+        Console.ForegroundColor = ConsoleColor.Cyan;
+        Console.WriteLine(title);
+        Console.ForegroundColor = ConsoleColor.DarkGray;
+        Console.WriteLine(subtitle);
+        Console.ForegroundColor = original;
+    }
+    else
+    {
+        Console.WriteLine(title);
+        Console.WriteLine(subtitle);
+    }
+}
+
+PrintBanner();
+
+/// <summary>
+/// Resolve a required configuration value or throw a friendly error.
+/// </summary>
 string RequiredSetting(string key, string? fallback = null)
 {
     var value = configuration[key];
@@ -60,6 +80,9 @@ string ProfileSourcePriority()
 }
 <% } -%>
 
+/// <summary>
+/// Create an app-only credential for Microsoft Graph.
+/// </summary>
 ClientSecretCredential CreateCredential()
 {
     var tenantId = RequiredSetting("AzureAd:TenantId");
@@ -68,6 +91,9 @@ ClientSecretCredential CreateCredential()
     return new ClientSecretCredential(tenantId, clientId, clientSecret);
 }
 
+/// <summary>
+/// Create a Graph client configured for the selected API version.
+/// </summary>
 GraphServiceClient CreateGraphClient()
 {
     var credential = CreateCredential();
@@ -76,135 +102,47 @@ GraphServiceClient CreateGraphClient()
     return graph;
 }
 
-<% if (isPeopleConnector) { -%>
-async Task<string> GetAccessTokenAsync(ClientSecretCredential credential)
+ConnectorCore BuildConnectorCore(GraphServiceClient? graph, ClientSecretCredential? credential, string connectionId)
 {
-    var token = await credential.GetTokenAsync(
-        new TokenRequestContext(new[] { "https://graph.microsoft.com/.default" })
+    return new ConnectorCore(
+        graph,
+        credential,
+        connectionId,
+        ConnectionName(),
+        ConnectionDescription(),
+        SchemaConstants.ContentCategory,
+        <%- isPeopleConnector ? "ProfileSourceWebUrl()" : "null" %>,
+        <%- isPeopleConnector ? "ProfileSourceDisplayName()" : "null" %>,
+        <%- isPeopleConnector ? "ProfileSourcePriority()" : "null" %>
     );
-    return token.Token;
-}
-
-async Task<HttpResponseMessage> GraphRequestAsync(ClientSecretCredential credential, HttpMethod method, string url, object? body = null)
-{
-    using var http = new HttpClient();
-    var token = await GetAccessTokenAsync(credential);
-    http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
-
-    var request = new HttpRequestMessage(method, url);
-    if (body is not null)
-    {
-        var json = JsonSerializer.Serialize(body);
-        request.Content = new StringContent(json, Encoding.UTF8, "application/json");
-    }
-
-    return await http.SendAsync(request);
-}
-<% } -%>
-
-bool IsStatus(ApiException ex, int statusCode)
-{
-    return ex.ResponseStatusCode is int sc && sc == statusCode;
-}
-
-async Task EnsureConnectionAsync(GraphServiceClient graph, string connectionId)
-{
-    try
-    {
-        await graph.External.Connections[connectionId].GetAsync();
-        return;
-    }
-    catch (ApiException ex) when (IsStatus(ex, 404))
-    {
-        // Create below.
-    }
-
-    var connection = new ExternalConnection
-    {
-        Id = connectionId,
-        Name = ConnectionName(),
-        Description = ConnectionDescription(),
-    };
-
-    if (!string.IsNullOrWhiteSpace(SchemaConstants.ContentCategory))
-    {
-        // contentCategory is currently only exposed on the /beta endpoint.
-        connection.AdditionalData ??= new Dictionary<string, object>();
-        connection.AdditionalData["contentCategory"] = SchemaConstants.ContentCategory!;
-    }
-
-    await graph.External.Connections.PostAsync(connection);
-}
-
-async Task PatchSchemaAsync(GraphServiceClient graph, string connectionId)
-{
-    var schema = SchemaPayload.BuildSchema();
-    await graph.External.Connections[connectionId].Schema.PatchAsync(schema);
 }
 
+/// <summary>
+/// Provision the connection and schema (and profile source for people connectors).
+/// </summary>
 async Task ProvisionAsync()
 {
     var graph = CreateGraphClient();
+    var credential = CreateCredential();
     var connectionId = ConnectionId();
+    var core = BuildConnectorCore(graph, credential, connectionId);
 
-    await EnsureConnectionAsync(graph, connectionId);
-    await PatchSchemaAsync(graph, connectionId);
-<% if (isPeopleConnector) { -%>
-    await RegisterProfileSourceAsync(connectionId);
-<% } -%>
-
+    await core.ProvisionAsync();
     Console.WriteLine("ok: provisioned");
 }
 
-async Task PutItemAsync(GraphServiceClient graph, string connectionId, Item item, bool verbose)
-{
-    var itemId = ItemPayload.GetItemId(item);
-
-    var externalItem = ItemPayload.ToExternalItem(item);
-    if (verbose)
-    {
-        var url = $"{graph.RequestAdapter.BaseUrl ?? SchemaConstants.GraphBaseUrl}/external/connections/{connectionId}/items/{Uri.EscapeDataString(itemId)}";
-        Console.WriteLine("verbose: PUT " + url);
-        Console.WriteLine("verbose: payload " + JsonSerializer.Serialize(externalItem, new JsonSerializerOptions { WriteIndented = true }));
-    }
-
-    // NOTE: The external connectors surface may not expose a typed PutAsync on all SDK versions.
-    // We still use the Graph SDK's request adapter and models for a strongly-typed payload.
-    var requestInfo = new RequestInformation
-    {
-        HttpMethod = Method.PUT,
-        UrlTemplate = "{+baseurl}/external/connections/{connectionId}/items/{itemId}",
-        PathParameters = new Dictionary<string, object>
-        {
-            { "baseurl", graph.RequestAdapter.BaseUrl ?? SchemaConstants.GraphBaseUrl },
-            { "connectionId", connectionId },
-            { "itemId", itemId },
-        },
-    };
-
-    requestInfo.Headers.Add("Accept", "application/json");
-    requestInfo.SetContentFromParsable(graph.RequestAdapter, "application/json", externalItem);
-
-    var errorMapping = new Dictionary<string, ParsableFactory<IParsable>>
-    {
-        { "4XX", ODataError.CreateFromDiscriminatorValue },
-        { "5XX", ODataError.CreateFromDiscriminatorValue },
-    };
-
-    await graph.RequestAdapter.SendAsync<ExternalItem>(
-        requestInfo,
-        ExternalItem.CreateFromDiscriminatorValue,
-        errorMapping
-    );
-}
-
+/// <summary>
+/// Ingest items from CSV.
+/// </summary>
 async Task IngestAsync(string? csvPath, bool dryRun, int? limit, bool verbose)
 {
     GraphServiceClient? graph = null;
-    string? connectionId = null;
+    ClientSecretCredential? credential = null;
+    string connectionId = "dry-run";
     if (!dryRun)
     {
         graph = CreateGraphClient();
+        credential = CreateCredential();
         connectionId = ConnectionId();
     }
 
@@ -213,163 +151,22 @@ async Task IngestAsync(string? csvPath, bool dryRun, int? limit, bool verbose)
 
     // Swap this for any IItemSource implementation (API, DB, queue, etc.).
     IItemSource source = new CsvItemSource(path);
+    var core = BuildConnectorCore(graph, credential, connectionId);
 
-    var count = 0;
-    await foreach (var item in source.GetItemsAsync())
-    {
-        if (limit.HasValue && count >= limit.Value)
-            break;
-        if (!dryRun)
-        {
-            await PutItemAsync(graph!, connectionId!, item, verbose);
-        }
-        else if (verbose)
-        {
-            Console.WriteLine("verbose: DRY RUN payload " + JsonSerializer.Serialize(ItemPayload.ToExternalItem(item), new JsonSerializerOptions { WriteIndented = true }));
-        }
-        count++;
-    }
-
-    Console.WriteLine($"ok: ingested {count} item(s)");
-}
-
-<% if (isPeopleConnector) { -%>
-async Task RegisterProfileSourceAsync(string connectionId)
-{
-    var credential = CreateCredential();
-    var webUrl = ProfileSourceWebUrl();
-    var displayName = ProfileSourceDisplayName();
-    var priority = ProfileSourcePriority();
-
-    var payload = new Dictionary<string, object?>
-    {
-        ["sourceId"] = connectionId,
-        ["displayName"] = displayName,
-        ["webUrl"] = webUrl,
-    };
-
-    var create = await GraphRequestAsync(
-        credential,
-        HttpMethod.Post,
-        $"{SchemaConstants.GraphBaseUrl}/admin/people/profileSources",
-        payload
-    );
-
-    if (!create.IsSuccessStatusCode && create.StatusCode != System.Net.HttpStatusCode.Conflict)
-    {
-        var text = await create.Content.ReadAsStringAsync();
-        throw new InvalidOperationException($"Failed to register profile source (HTTP {(int)create.StatusCode}): {text}");
-    }
-
-    var sourceUrl = $"{SchemaConstants.GraphBaseUrl}/admin/people/profileSources(sourceId='{connectionId}')";
-    await UpdateProfileSourcePrecedenceAsync(credential, sourceUrl, include: true, priority: priority);
-}
-
-async Task UnregisterProfileSourceAsync(string connectionId)
-{
-    var credential = CreateCredential();
-    var sourceUrl = $"{SchemaConstants.GraphBaseUrl}/admin/people/profileSources(sourceId='{connectionId}')";
-
-    await UpdateProfileSourcePrecedenceAsync(credential, sourceUrl, include: false, priority: "first");
-
-    var res = await GraphRequestAsync(
-        credential,
-        HttpMethod.Delete,
-        $"{SchemaConstants.GraphBaseUrl}/admin/people/profileSources(sourceId='{connectionId}')"
-    );
-
-    if (!res.IsSuccessStatusCode && res.StatusCode != System.Net.HttpStatusCode.NotFound)
-    {
-        var text = await res.Content.ReadAsStringAsync();
-        throw new InvalidOperationException($"Failed to delete profile source (HTTP {(int)res.StatusCode}): {text}");
-    }
+    await core.IngestAsync(source, dryRun, limit, verbose);
 }
 
-async Task UpdateProfileSourcePrecedenceAsync(ClientSecretCredential credential, string sourceUrl, bool include, string priority)
-{
-    var res = await GraphRequestAsync(
-        credential,
-        HttpMethod.Get,
-        $"{SchemaConstants.GraphBaseUrl}/admin/people/profilePropertySettings"
-    );
-
-    if (!res.IsSuccessStatusCode)
-    {
-        var text = await res.Content.ReadAsStringAsync();
-        throw new InvalidOperationException($"Failed to list profile property settings (HTTP {(int)res.StatusCode}): {text}");
-    }
-
-    var json = await res.Content.ReadAsStringAsync();
-    using var doc = JsonDocument.Parse(json);
-    if (!doc.RootElement.TryGetProperty("value", out var values) || values.ValueKind != JsonValueKind.Array)
-        return;
-
-    foreach (var entry in values.EnumerateArray())
-    {
-        if (!entry.TryGetProperty("id", out var idProp) || idProp.ValueKind != JsonValueKind.String)
-            continue;
-
-        var id = idProp.GetString() ?? string.Empty;
-        if (string.IsNullOrWhiteSpace(id)) continue;
-
-        List<string> existing = new();
-        if (entry.TryGetProperty("prioritizedSourceUrls", out var urls) && urls.ValueKind == JsonValueKind.Array)
-        {
-            foreach (var url in urls.EnumerateArray())
-            {
-                if (url.ValueKind == JsonValueKind.String)
-                    existing.Add(url.GetString() ?? "");
-            }
-        }
-
-        existing = existing.Where((u) => !string.IsNullOrWhiteSpace(u) && u != sourceUrl).ToList();
-        var updated = existing;
-        if (include)
-        {
-            updated = priority == "last"
-                ? existing.Concat(new[] { sourceUrl }).ToList()
-                : new[] { sourceUrl }.Concat(existing).ToList();
-        }
-
-        var patch = new Dictionary<string, object?>
-        {
-            ["@odata.type"] = "#microsoft.graph.profilePropertySetting",
-            ["prioritizedSourceUrls"] = updated,
-        };
-
-        var patchRes = await GraphRequestAsync(
-            credential,
-            HttpMethod.Patch,
-            $"{SchemaConstants.GraphBaseUrl}/admin/people/profilePropertySettings/{id}",
-            patch
-        );
-
-        if (!patchRes.IsSuccessStatusCode)
-        {
-            var text = await patchRes.Content.ReadAsStringAsync();
-            throw new InvalidOperationException($"Failed to update profile property setting {id} (HTTP {(int)patchRes.StatusCode}): {text}");
-        }
-    }
-}
-<% } -%>
-
+/// <summary>
+/// Delete the external connection.
+/// </summary>
 async Task DeleteConnectionAsync()
 {
     var graph = CreateGraphClient();
+    var credential = CreateCredential();
     var connectionId = ConnectionId();
+    var core = BuildConnectorCore(graph, credential, connectionId);
 
-<% if (isPeopleConnector) { -%>
-    await UnregisterProfileSourceAsync(connectionId);
-<% } -%>
-
-    try
-    {
-        await graph.External.Connections[connectionId].DeleteAsync();
-    }
-    catch (ApiException ex) when (IsStatus(ex, 404))
-    {
-        // Already deleted.
-    }
+    await core.DeleteConnectionAsync();
     Console.WriteLine("ok: deleted");
 }
 
@@ -405,7 +202,14 @@ root.AddCommand(deleteCommand);
 
 <% if (isPeopleConnector) { -%>
 var registerCommand = new Command("register-profile-source", "Register the connection as a profile source");
-registerCommand.SetHandler(async () => await RegisterProfileSourceAsync(ConnectionId()));
+registerCommand.SetHandler(async () =>
+{
+    var graph = CreateGraphClient();
+    var credential = CreateCredential();
+    var connectionId = ConnectionId();
+    var core = BuildConnectorCore(graph, credential, connectionId);
+    await core.RegisterProfileSourceAsync();
+});
 root.AddCommand(registerCommand);
 <% } -%>
 
@@ -413,12 +217,6 @@ try
 {
     return await root.InvokeAsync(args);
 }
-catch (ApiException ex)
-{
-    Console.Error.WriteLine("error: Graph request failed");
-    Console.Error.WriteLine(ex.Message);
-    return 1;
-}
 catch (Exception ex)
 {
     Console.Error.WriteLine("error: " + ex.Message);

package/dist/init/templates/dotnet/PropertyTransform.cs.ejs

@@ -0,0 +1,10 @@
+// Customize CSV-to-model property transforms.
+namespace <%= schemaNamespace %>;
+
+/// <summary>
+/// User-overridable transforms for schema fields.
+/// </summary>
+public sealed class PropertyTransform : PropertyTransformBase
+{
+    // Override Transform<PropName> methods to customize mapping.
+}

package/dist/init/templates/dotnet/README.md.ejs

@@ -31,13 +31,12 @@ This project includes `tspconfig.yaml` and a `package.json` with `@wictorwilen/c
 Run `npm install` in this folder to fetch the TypeSpec library.
 
 ## Customizing the project
-- **Schema and fields**: edit `schema.tsp` (copied into this folder) and run `cocogen update --out .` to regenerate `Schema/`.
+- **Schema and fields**: edit `schema.tsp` (copied into this folder) and run `cocogen update --out .` to regenerate `<%= schemaFolderName %>/`.
 - **Ingestion**: replace the datasource in `Datasource/` (CSV is the default) and wire it in `Program.cs`.
-- **People connectors**: customize entity payloads in `Schema/PersonEntityOverrides.cs` (kept on updates).
-- **Property transforms**: edit `Schema/PropertyTransforms.cs` to customize per-field parsing/mapping.
-- **Connection defaults**: `@coco.connection` can set `connectionId` and `connectionDescription` defaults for `appsettings.json`.
+- **Property transforms**: edit `<%= schemaFolderName %>/PropertyTransform.cs` (kept on updates) to customize per-field parsing/mapping.
+- **Connection defaults**: `@coco.connection` must set `name`, `connectionId`, and `connectionDescription` defaults for `appsettings.json`.
 - **Profile source defaults**: `@coco.profileSource` sets defaults for `ProfileSource` settings (people connectors only).
-- **Access control**: edit `Schema/ItemPayload.cs` to change ACL behavior.
+- **Access control**: edit `<%= schemaFolderName %>/ItemPayload.cs` to change ACL behavior.
 
 ## Ingest debugging flags
 Use `dotnet run -- ingest` with:
@@ -49,8 +48,8 @@ Note: `--dry-run` does not require Azure AD or connection settings.
 
 ## Switching from CSV to another datasource
 1) Implement `IItemSource` in `Datasource/`.
-2) If your source yields raw records, map them to `Item` using `FromCsvRow`-style logic.
+2) If your source yields raw records, map them to `<%= itemTypeName %>` using `FromCsvRow`-style logic.
 3) Update `Program.cs` to instantiate your new source instead of `CsvItemSource`.
 
-Tip: keep the `IAsyncEnumerable<Item>` pattern for large datasets.
+Tip: keep the `IAsyncEnumerable<<%= itemTypeName %>>` pattern for large datasets.
 

package/dist/init/templates/dotnet/appsettings.json.ejs

@@ -6,7 +6,7 @@
   },
   "Connection": {
     "Id": "<%= connectionId ?? "my-connection-id" %>",
-    "Name": "<%= itemTypeName %>",
+    "Name": "<%= connectionName ?? itemTypeName %>",
     "Description": "<%= connectionDescription ?? `${itemTypeName} connector generated by cocogen` %>"
   },
   "Csv": {

package/dist/init/templates/ts/.env.example.ejs

@@ -5,7 +5,7 @@ CLIENT_SECRET=
 
 # Graph external connection
 CONNECTION_ID=<%= connectionId ?? "my-connection-id" %>
-CONNECTION_NAME=<%= itemTypeName %>
+CONNECTION_NAME=<%= connectionName ?? itemTypeName %>
 CONNECTION_DESCRIPTION=<%= connectionDescription ?? `${itemTypeName} connector generated by cocogen` %>
 
 <% if (isPeopleConnector) { -%>

package/dist/init/templates/ts/AGENTS.md.ejs

@@ -0,0 +1,20 @@
+# AGENTS.md
+
+This project was generated by cocogen. This file is safe to edit.
+
+## Update after TypeSpec changes
+1) Edit `schema.tsp`.
+2) Regenerate schema-derived code:
+   - `npx @wictorwilen/cocogen@latest update --out .`
+   - or `cocogen update --out .`
+3) If the TypeSpec path changed:
+   - `npx @wictorwilen/cocogen@latest update --out . --tsp ../schema.tsp`
+
+Only `src/<%= schemaFolderName %>/**` is overwritten by `cocogen update`.
+
+## Customize property transforms
+Edit `src/<%= schemaFolderName %>/propertyTransform.ts` (safe file). The generated base lives in `src/<%= schemaFolderName %>/propertyTransformBase.ts`.
+
+## Switch datasource / backend
+1) Implement `ItemSource` in `src/datasource`.
+2) Update `src/cli.ts` to use your source instead of `CsvItemSource`.

package/dist/init/templates/ts/README.md.ejs

@@ -27,13 +27,12 @@ This project includes `tspconfig.yaml` and a devDependency on `@wictorwilen/coco
 Run `npm install` to fetch the TypeSpec library.
 
 ## Customizing the project
-- **Schema and fields**: edit `schema.tsp` (copied into this folder) and run `cocogen update --out .` to regenerate `src/schema`.
+- **Schema and fields**: edit `schema.tsp` (copied into this folder) and run `cocogen update --out .` to regenerate `src/<%= schemaFolderName %>`.
 - **Ingestion**: replace the datasource in `src/datasource` (CSV is the default) and wire it in `src/cli.ts`.
-- **People connectors**: customize entity payloads in `src/schema/personEntityOverrides.ts` (kept on updates).
-- **Property transforms**: edit `src/schema/propertyTransforms.ts` to customize per-field parsing/mapping.
-- **Connection defaults**: `@coco.connection` can set `connectionId` and `connectionDescription` defaults for `.env.example`.
+- **Property transforms**: edit `src/<%= schemaFolderName %>/propertyTransform.ts` (kept on updates) to customize per-field parsing/mapping.
+- **Connection defaults**: `@coco.connection` must set `name`, `connectionId`, and `connectionDescription` defaults for `.env.example`.
 - **Profile source defaults**: `@coco.profileSource` sets defaults for `PROFILE_SOURCE_*` (people connectors only).
-- **Access control**: edit `src/schema/itemPayload.ts` to change ACL behavior.
+- **Access control**: edit `src/<%= schemaFolderName %>/itemPayload.ts` to change ACL behavior.
 
 ## Ingest debugging flags
 Use `npm run ingest --` with:
@@ -45,10 +44,10 @@ Note: `--dry-run` does not require CONNECTION_ID, but you still need it for real
 
 ## Switching from CSV to another datasource
 1) Implement `ItemSource` in `src/datasource`.
-2) If your source yields raw records, map them to `Item` using `fromCsvRow`-style logic.
+2) If your source yields raw records, map them to `<%= itemTypeName %>` using `fromCsvRow`-style logic.
 3) Update `src/cli.ts` to instantiate your new source instead of `CsvItemSource`.
 
-Tip: keep the streaming `AsyncIterable<Item>` pattern for large datasets.
+Tip: keep the streaming `AsyncIterable<<%= itemTypeName %>>` pattern for large datasets.
 
 ## Multiple connections
 This generated CLI currently targets a single connection ID from environment variables. Multi-connection support is planned for a future version.