feat: follow the addon renames, and make the Datadog preload actually work

Three catalog packages were renamed on npm: @imqueue/opentelemetry-instrumentation-imqueue
to @imqueue/opentelemetry, @imqueue/sequelize to @imqueue/pg-sequelize, and
@imqueue/dd-trace to @imqueue/datadog. No shim was published, so the old names
stay installable and frozen.

Catalog ids are unchanged — `dd-trace` and `sequelize` stay as they are. They are
what `--packages` takes and what ~/.imq/config.json and .imqrc.json hold, and
validateSelection() rejects an id it does not know, so renaming them would turn
every stored selection into a hard "Unknown package" error. The wiki now says
plainly that two ids no longer match their npm names.

Fleet probes accept BOTH names per member. usesMember() tested one exact string,
so swapping in the new names alone would have made every unmigrated service
invisible: a ten-service Sequelize fleet would read as "no ORM anywhere" and the
prompt would recommend pg-prisma into it. No error, no failing test either — the
existing assertions are all about ids. ProbeMember.dep now takes a string or a
list, and four cases cover old-only and mixed fleets.

Also fixes a bug the rename would otherwise have been blamed for: the dd-trace
addon's preload was `import '@imqueue/dd-trace';`, which installs the tracing
hooks but never calls tracer.init() — and init() is what enables the imq
integration and starts reporting. Every service ever scaffolded with that addon
has been sending nothing to Datadog. The preload now imports a generated
src/tracer.ts that calls init(), mirroring how opentelemetry uses
src/telemetry.ts. It has to be a separate module: %ADDON_PRELOAD sits at the top
of src/index.ts and ESM evaluates all imports before any body statement, so an
inline init() would run after the config and service-class modules.

generateAddons() had no test coverage at all; it has three now, including one
asserting the generated tracer calls init(). The generated import specifiers are
string content, so tsc cannot check them — a stale one only shows up at the
user's npm install.

README's orm group listed `prisma`, which was replaced by `pg-prisma` in b27a4be.

Author: Mikhus

README.md

@@ -158,7 +158,7 @@ new addons can be published without a CLI release. Groups marked *exclusive*
 allow a single choice:
 
 - **tracing** (exclusive): `dd-trace`, `opentelemetry`
-- **orm** (exclusive): `sequelize`, `prisma`
+- **orm** (exclusive): `sequelize`, `pg-prisma`
 - **features**: `pg-cache`, `pg-pubsub`, `tag-cache`, `job`, `net`,
   `http-protect`, `graphql-dependency`, `type-graphql-dependency`
 

lib/catalog.json

@@ -19,7 +19,7 @@
       "title": "OpenTelemetry instrumentation",
       "pick": "Recommended: vendor-neutral, so the backend can change without touching service code.",
       "deps": {
-        "@imqueue/opentelemetry-instrumentation-imqueue": "*",
+        "@imqueue/opentelemetry": "*",
         "@opentelemetry/api": "*",
         "@opentelemetry/instrumentation": "*",
         "@opentelemetry/resources": "*",
@@ -44,22 +44,23 @@
     },
     "dd-trace": {
       "group": "tracing",
-      "title": "Datadog APM (dd-trace)",
+      "title": "Datadog APM",
       "hint": "already on Datadog",
       "pick": "For a fleet already standing on Datadog\u2019s own agent; otherwise take opentelemetry.",
-      "deps": { "@imqueue/dd-trace": "*" },
-      "snippets": { "preload": "import '@imqueue/dd-trace';" },
+      "deps": { "@imqueue/datadog": "*" },
+      "snippets": { "preload": "import './tracer.js';" },
       "env": ["DD_AGENT_HOST", "DD_TRACE_ENABLED"],
       "instructions": [
+        "Datadog: tracing is initialized in src/tracer.ts (imported first at start-up).",
         "Datadog: ensure a Datadog agent is reachable via DD_AGENT_HOST."
       ]
     },
     "sequelize": {
       "group": "orm",
-      "title": "Sequelize ORM + @imqueue/sequelize toolkit",
+      "title": "Sequelize ORM + @imqueue/pg-sequelize toolkit",
       "hint": "match a Sequelize fleet",
       "pick": "For a service joining a fleet already built on Sequelize, where matching the existing stack is worth more than the default. Migrating the fleet to pg-prisma is worth proposing, as separate work.",
-      "deps": { "@imqueue/sequelize": "*", "sequelize": "*" },
+      "deps": { "@imqueue/pg-sequelize": "*", "sequelize": "*" },
       "instructions": [
         "Sequelize: configure your database connection in config.ts."
       ]

src/catalog/fleet.ts

@@ -42,8 +42,16 @@ import { VAR_HOME, resolve } from '../../lib/index.js';
 interface ProbeMember {
     /** Catalog id, provider id — whatever the prompt for this group selects. */
     id: string;
-    /** A dependency in the service's package.json. */
-    dep?: string;
+    /**
+     * A dependency in the service's package.json, or several.
+     *
+     * A list is how a renamed package stays detectable: every name the package
+     * has shipped under counts as evidence. Without that, the rename of an addon
+     * would make every service that has not migrated yet invisible to the probe,
+     * and the group would report nothing detected — no error, just a
+     * recommendation that steers a fleet off its own stack.
+     */
+    dep?: string | string[];
     /** A path inside the service, file or directory. */
     files?: string[];
     /** A substring of a remote URL in the service's .git/config. */
@@ -102,7 +110,10 @@ const PROBES: GroupProbe[] = [
         label: 'ORM',
         kind: 'catalog',
         members: [
-            { id: 'sequelize', dep: '@imqueue/sequelize' },
+            {
+                id: 'sequelize',
+                dep: ['@imqueue/pg-sequelize', '@imqueue/sequelize'],
+            },
             { id: 'pg-prisma', dep: '@imqueue/pg-prisma' },
         ],
         recommended: 'pg-prisma',
@@ -115,9 +126,15 @@ const PROBES: GroupProbe[] = [
         members: [
             {
                 id: 'opentelemetry',
-                dep: '@imqueue/opentelemetry-instrumentation-imqueue',
+                dep: [
+                    '@imqueue/opentelemetry',
+                    '@imqueue/opentelemetry-instrumentation-imqueue',
+                ],
+            },
+            {
+                id: 'dd-trace',
+                dep: ['@imqueue/datadog', '@imqueue/dd-trace'],
             },
-            { id: 'dd-trace', dep: '@imqueue/dd-trace' },
         ],
         recommended: 'opentelemetry',
         baseline: 'opentelemetry',
@@ -334,8 +351,12 @@ function usesMember(
     remotes: string,
     member: ProbeMember,
 ): boolean {
-    if (member.dep && deps.has(member.dep)) {
-        return true;
+    if (member.dep) {
+        const names = Array.isArray(member.dep) ? member.dep : [member.dep];
+
+        if (names.some(name => deps.has(name))) {
+            return true;
+        }
     }
 
     if (member.files?.some(file => existsSync(join(dir, file)))) {

src/service/create-scaffold.ts

@@ -718,6 +718,31 @@ function telemetryServiceName(
           };
 }
 
+/**
+ * Datadog APM setup.
+ *
+ * @remarks
+ * A separate module rather than an inline statement in the preload slot, and that
+ * is load-bearing. `%ADDON_PRELOAD` sits at the top of the generated
+ * `src/index.ts`, and ESM evaluates every import of a module before any of its
+ * body statements — so an inline `tracer.init()` there would run *after*
+ * `./config.js` and the service class module had already been evaluated, which is
+ * exactly what it needs to precede. The catalog's preload therefore imports this
+ * file, and the `init()` call happens during that import.
+ */
+function tracerModule(header: string): string {
+    return `${header}
+import tracer from '@imqueue/datadog';
+
+// Importing the package installs the tracing hooks; init() is what enables the
+// imq integration and starts reporting. Every client and service constructed
+// after this point is traced, with no change to application code.
+tracer.init();
+
+export default tracer;
+`;
+}
+
 /** OpenTelemetry setup without a trace exporter (add one, e.g. the gcp pkg). */
 function telemetryBase(
     header: string,
@@ -730,7 +755,7 @@ function telemetryBase(
 ${telemetryEnvDefaultsImport(isV2)}import {
     ImqueueInstrumentation,
     type RpcModule,
-} from '@imqueue/opentelemetry-instrumentation-imqueue';
+} from '@imqueue/opentelemetry';
 import { resourceFromAttributes } from '@opentelemetry/resources';
 import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
 import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
@@ -769,7 +794,7 @@ ${telemetryEnvDefaultsImport(isV2)}import { TraceExporter } from '@google-cloud/
 import {
     ImqueueInstrumentation,
     type RpcModule,
-} from '@imqueue/opentelemetry-instrumentation-imqueue';
+} from '@imqueue/opentelemetry';
 import { resourceFromAttributes } from '@opentelemetry/resources';
 import {
     BatchSpanProcessor,
@@ -889,6 +914,11 @@ export function generateAddons(
         );
     }
 
+    if (has('dd-trace')) {
+        console.log('Generating Datadog setup...');
+        touch(resolve(path, 'src', 'tracer.ts'), tracerModule(header));
+    }
+
     if (hasPgPrisma) {
         console.log('Generating @imqueue/pg-prisma setup...');
 

test/src/catalog/catalog.spec.ts

@@ -101,9 +101,12 @@ describe('package catalog', () => {
         it('should aggregate deps, snippets, env and instructions', () => {
             const addons = resolveAddons(['dd-trace', 'pg-cache'], catalog);
 
-            assert.equal(addons.deps['@imqueue/dd-trace'], '*');
+            assert.equal(addons.deps['@imqueue/datadog'], '*');
             assert.equal(addons.deps['@imqueue/pg-cache'], '*');
-            assert.match(addons.preload, /@imqueue\/dd-trace/);
+            // The preload imports the generated ./tracer.js rather than the
+            // package: a bare `import '@imqueue/datadog'` installs the hooks but
+            // never calls tracer.init(), so nothing is reported.
+            assert.match(addons.preload, /\.\/tracer\.js/);
             assert.ok(addons.hasSnippets);
             assert.ok(addons.env.includes('DD_AGENT_HOST'));
             assert.ok(addons.instructions.length > 0);

test/src/catalog/fleet.spec.ts

@@ -78,11 +78,20 @@ function service(root: string, name: string, deps: string[]): void {
 }
 
 const RPC = '@imqueue/rpc';
-const OTEL = '@imqueue/opentelemetry-instrumentation-imqueue';
-const DD = '@imqueue/dd-trace';
-const SEQ = '@imqueue/sequelize';
+const OTEL = '@imqueue/opentelemetry';
+const DD = '@imqueue/datadog';
+const SEQ = '@imqueue/pg-sequelize';
 const PRISMA = '@imqueue/pg-prisma';
 
+// The names these three shipped under before the rename. Existing services still
+// declare them — deprecating a package does not uninstall it — so the probes must
+// keep recognising them. Without these cases a rename that missed the old names
+// would leave every unmigrated fleet reading as "nothing detected", and the suite
+// would stay green because the assertions elsewhere are all about catalog ids.
+const OTEL_OLD = '@imqueue/opentelemetry-instrumentation-imqueue';
+const DD_OLD = '@imqueue/dd-trace';
+const SEQ_OLD = '@imqueue/sequelize';
+
 describe('analyseFleet()', () => {
     const fleets: string[] = [];
 
@@ -124,6 +133,30 @@ describe('analyseFleet()', () => {
         );
     });
 
+    it('still reads a fleet on the pre-rename ORM name as sequelize', () => {
+        const root = fleet();
+
+        service(root, 'auth', [RPC, SEQ_OLD]);
+        service(root, 'billing', [RPC, SEQ_OLD]);
+
+        const analysis = analyseFleet(root);
+
+        assert.equal(orm(analysis).propose, 'sequelize');
+        assert.equal(orm(analysis).counts.sequelize, 2);
+    });
+
+    it('counts old and new ORM names as the same member', () => {
+        const root = fleet();
+
+        service(root, 'auth', [RPC, SEQ]);
+        service(root, 'billing', [RPC, SEQ_OLD]);
+
+        const analysis = analyseFleet(root);
+
+        assert.equal(orm(analysis).propose, 'sequelize');
+        assert.equal(orm(analysis).counts.sequelize, 2);
+    });
+
     it('reads a Prisma fleet as pg-prisma', () => {
         const root = fleet();
 
@@ -306,6 +339,30 @@ describe('analyseFleet() tracing', () => {
         assert.match(fleetNotes(analysis).tracing, /^Preselected dd-trace/);
     });
 
+    it('still reads a fleet on the pre-rename tracing names', () => {
+        const root = fleet();
+
+        service(root, 'auth', [RPC, DD_OLD]);
+        service(root, 'billing', [RPC, DD_OLD]);
+
+        const analysis = analyseFleet(root);
+
+        assert.equal(tracing(analysis).propose, 'dd-trace');
+        assert.equal(tracing(analysis).counts['dd-trace'], 2);
+    });
+
+    it('counts old and new OpenTelemetry names as the same member', () => {
+        const root = fleet();
+
+        service(root, 'auth', [RPC, OTEL]);
+        service(root, 'billing', [RPC, OTEL_OLD]);
+
+        const analysis = analyseFleet(root);
+
+        assert.equal(tracing(analysis).propose, 'opentelemetry');
+        assert.equal(tracing(analysis).counts.opentelemetry, 2);
+    });
+
     it('proposes the recommended backend when a fleet uses both', () => {
         const root = fleet();
 

test/src/service/create-scaffold.spec.ts

@@ -38,6 +38,7 @@ import {
     buildServiceTokens,
     compileTemplate,
     ensureTemplate,
+    generateAddons,
     isEsmService,
     loadTemplateManifest,
     overlayFragments,
@@ -227,4 +228,43 @@ describe('service create scaffolding', () => {
             );
         });
     });
+
+    describe('generateAddons()', () => {
+        function addons(id: string): string {
+            const sub = join(dir, `addons-${id}`);
+
+            mkdirSync(join(sub, 'src'), { recursive: true });
+            generateAddons(sub, '// header', [id], true, 'svc');
+
+            return sub;
+        }
+
+        it('should write a telemetry module for opentelemetry', () => {
+            const sub = addons('opentelemetry');
+            const src = readFileSync(join(sub, 'src', 'telemetry.ts'), 'utf8');
+
+            // the import specifier is generated source: tsc cannot check it,
+            // and a stale one only fails at the user's npm install
+            assert.match(src, /from '@imqueue\/opentelemetry'/);
+            assert.doesNotMatch(src, /opentelemetry-instrumentation-imqueue/);
+        });
+
+        it('should write a tracer module for dd-trace that calls init()', () => {
+            const sub = addons('dd-trace');
+            const src = readFileSync(join(sub, 'src', 'tracer.ts'), 'utf8');
+
+            assert.match(src, /from '@imqueue\/datadog'/);
+            // init() is the whole point of the file. Importing the package alone
+            // installs the hooks but reports nothing, which is what the previous
+            // bare-import preload did.
+            assert.match(src, /tracer\.init\(\);/);
+        });
+
+        it('should write nothing for a deps-only addon', () => {
+            const sub = addons('pg-cache');
+
+            assert.ok(!existsSync(join(sub, 'src', 'telemetry.ts')));
+            assert.ok(!existsSync(join(sub, 'src', 'tracer.ts')));
+        });
+    });
 });

wiki/Package-Catalog.md

@@ -36,6 +36,12 @@ service that talks to no database it is the right one.
 | **ORM / database** | yes | `pg-prisma`, `sequelize` |
 | **Service features** | no | `pg-cache`, `pg-pubsub`, `tag-cache`, `job`, `net`, `http-protect`, `graphql-dependency`, `type-graphql-dependency` |
 
+These are catalog **ids** — what `--packages` takes and what a saved config
+holds — not npm package names, and two of them no longer match. `dd-trace`
+installs `@imqueue/datadog` and `sequelize` installs `@imqueue/pg-sequelize`,
+both renamed while the ids stayed put so that existing configs and `.imqrc.json`
+files keep working.
+
 ## What each addon does when selected
 
 For every selected package the scaffolder:
@@ -76,7 +82,7 @@ recommended one, with a line above the list saying why:
   pg-prisma is worth considering — as its own piece of work, not as part of this.
   (none)
   Prisma ORM + @imqueue/pg-prisma toolkit
-❯ Sequelize ORM + @imqueue/sequelize toolkit (recommended)
+❯ Sequelize ORM + @imqueue/pg-sequelize toolkit (recommended)
 ```
 
 A new service in an established fleet belongs on the fleet's stack: matching