feat: add find instances ipc call and supersededBy flag

Author: kevinwang5658

.npmrc

@@ -1 +1,2 @@
 min-release-age=7
+min-release-age-exclude[]=@codifycli/*

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@codifycli/plugin-core",
-  "version": "1.2.11",
+  "version": "1.3.0",
   "description": "TypeScript library for building Codify plugins to manage system resources (applications, CLI tools, settings) through infrastructure-as-code",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
@@ -35,7 +35,7 @@
   },
   "license": "ISC",
   "dependencies": {
-    "@codifycli/schemas": "^1.2.0",
+    "@codifycli/schemas": "^1.4.0",
     "ajv": "^8.18.0",
     "ajv-formats": "^2.1.1",
     "clean-deep": "^3.4.0",

package.json

@@ -1,6 +1,8 @@
 import {
   ApplyRequestDataSchema,
   EmptyResponseDataSchema,
+  FindInstancesRequestDataSchema,
+  FindInstancesResponseDataSchema,
   GetResourceInfoRequestDataSchema,
   GetResourceInfoResponseDataSchema,
   ImportRequestDataSchema,
@@ -63,6 +65,11 @@ const SupportedRequests: Record<string, { handler: (plugin: Plugin, data: any) =
     requestValidator: ImportRequestDataSchema,
     responseValidator: ImportResponseDataSchema
   },
+  'findInstances': {
+    handler: async (plugin: Plugin, data: any) => plugin.findInstances(data),
+    requestValidator: FindInstancesRequestDataSchema,
+    responseValidator: FindInstancesResponseDataSchema
+  },
   'plan': {
     handler: async (plugin: Plugin, data: any) => plugin.plan(data),
     requestValidator: PlanRequestDataSchema,

src/messages/handlers.ts

@@ -530,4 +530,120 @@ describe('Plugin tests', () => {
       })
     ).rejects.toThrowError();
   })
+
+  describe('findInstances', () => {
+    class MultipleResource extends TestResource {
+      findAllCalls = 0;
+
+      getSettings(): ResourceSettings<TestConfig> {
+        return {
+          id: 'testResource',
+          operatingSystems: [OS.Darwin],
+          importAndDestroy: {
+            preventImport: true,
+          },
+          allowMultiple: {
+            identifyingParameters: ['propA'],
+            findAllParameters: async () => {
+              this.findAllCalls++;
+              return [{ propA: 'a' }, { propA: 'b' }, { propA: 'missing' }];
+            },
+          },
+        }
+      }
+
+      async refresh(parameters: Partial<TestConfig>): Promise<Partial<TestConfig> | null> {
+        if (parameters.propA === 'missing') {
+          return null;
+        }
+
+        return { propA: parameters.propA, propB: 10 };
+      }
+    }
+
+    it('Finds every existing instance even if the resource prevents imports', async () => {
+      const resource = new MultipleResource();
+      const testPlugin = Plugin.create('testPlugin', [resource]);
+
+      const result = await testPlugin.findInstances({ core: { type: 'testResource' } });
+
+      expect(result.request).toMatchObject({ core: { type: 'testResource' } });
+      expect(result.result).toEqual([
+        { core: { type: 'testResource' }, parameters: { propA: 'a', propB: 10 } },
+        { core: { type: 'testResource' }, parameters: { propA: 'b', propB: 10 } },
+      ]);
+      expect(resource.findAllCalls).to.eq(1);
+    })
+
+    it('Still prevents imports when preventImport is set', async () => {
+      const testPlugin = Plugin.create('testPlugin', [new MultipleResource()]);
+
+      await expect(testPlugin.import({ core: { type: 'testResource' }, parameters: {}, autoSearchAll: true }))
+        .rejects.toThrowError();
+    })
+
+    it('Import all uses the same discovery and only calls findAllParameters once', async () => {
+      const resource = new class extends MultipleResource {
+        getSettings(): ResourceSettings<TestConfig> {
+          return { ...super.getSettings(), importAndDestroy: undefined };
+        }
+      }
+      const testPlugin = Plugin.create('testPlugin', [resource]);
+
+      const result = await testPlugin.import({ core: { type: 'testResource' }, parameters: {}, autoSearchAll: true });
+
+      expect(result.result.map((r) => r.parameters.propA)).toEqual(['a', 'b']);
+      expect(resource.findAllCalls).to.eq(1);
+    })
+
+    it('Returns nothing if the resource can not discover instances', async () => {
+      const singleton = Plugin.create('testPlugin', [new TestResource()]);
+      expect((await singleton.findInstances({ core: { type: 'testResource' } })).result).toEqual([]);
+
+      const noFindAll = Plugin.create('testPlugin', [new class extends TestResource {
+        getSettings(): ResourceSettings<TestConfig> {
+          return { ...super.getSettings(), allowMultiple: { identifyingParameters: ['propA'] } };
+        }
+      }]);
+      expect((await noFindAll.findInstances({ core: { type: 'testResource' } })).result).toEqual([]);
+    })
+
+    it('Errors for unknown resources', async () => {
+      const testPlugin = Plugin.create('testPlugin', [new TestResource()]);
+      await expect(testPlugin.findInstances({ core: { type: 'unknown' } })).rejects.toThrowError();
+    })
+  })
+
+  describe('supersededBy', () => {
+    const singular = new class extends TestResource {
+      getSettings(): ResourceSettings<TestConfig> {
+        return { id: 'singular', operatingSystems: [OS.Darwin], importAndDestroy: { supersededBy: 'plural' } };
+      }
+    }
+
+    const plural = new class extends TestResource {
+      getSettings(): ResourceSettings<TestConfig> {
+        return { id: 'plural', operatingSystems: [OS.Darwin] };
+      }
+    }
+
+    it('Returns supersededBy in the resource definitions', async () => {
+      const testPlugin = Plugin.create('testPlugin', [singular, plural]);
+      const { resourceDefinitions } = await testPlugin.initialize({});
+
+      expect(resourceDefinitions.find((d) => d.type === 'singular')?.supersededBy).to.eq('plural');
+      expect(resourceDefinitions.find((d) => d.type === 'plural')?.supersededBy).to.be.undefined;
+    })
+
+    it('Errors if supersededBy is not another resource in the plugin', () => {
+      expect(() => Plugin.create('testPlugin', [singular])).toThrowError(/supersededBy/);
+
+      const self = new class extends TestResource {
+        getSettings(): ResourceSettings<TestConfig> {
+          return { id: 'self', operatingSystems: [OS.Darwin], importAndDestroy: { supersededBy: 'self' } };
+        }
+      }
+      expect(() => Plugin.create('testPlugin', [self])).toThrowError(/supersededBy/);
+    })
+  })
 });

src/plugin/plugin.test.ts

@@ -1,5 +1,7 @@
 import {
   ApplyRequestData,
+  FindInstancesRequestData,
+  FindInstancesResponseData,
   GetResourceInfoRequestData,
   GetResourceInfoResponseData,
   ImportRequestData,
@@ -54,6 +56,13 @@ export class Plugin {
       controllers.map((r) => [r.typeId, r] as const)
     );
 
+    for (const controller of controllers) {
+      const supersededBy = controller.settings.importAndDestroy?.supersededBy;
+      if (supersededBy !== undefined && (supersededBy === controller.typeId || !controllersMap.has(supersededBy))) {
+        throw new Error(`Resource: ${controller.typeId}. importAndDestroy.supersededBy must be the type of another resource in this plugin. Received: ${supersededBy}`);
+      }
+    }
+
     return new Plugin(name, controllersMap, options);
   }
 
@@ -87,6 +96,7 @@ export class Plugin {
             sensitiveParameters,
             operatingSystems: r.settings.operatingSystems,
             linuxDistros: r.settings.linuxDistros,
+            supersededBy: r.settings.importAndDestroy?.supersededBy,
           }
         })
     }
@@ -173,6 +183,25 @@ export class Plugin {
     }
   }
 
+  async findInstances(data: FindInstancesRequestData): Promise<FindInstancesResponseData> {
+    const { core } = data;
+
+    if (!this.resourceControllers.has(core.type)) {
+      throw new Error(`Cannot find instances for resource ${core.type}, resource doesn't exist`);
+    }
+
+    const result = await ptyLocalStorage.run(this.planPty, () =>
+      this.resourceControllers
+        .get(core.type)!
+        .findInstances(core)
+    )
+
+    return {
+      request: data,
+      result,
+    }
+  }
+
   async validate(data: ValidateRequestData): Promise<ValidateResponseData> {
     const validationResults: ValidateResponseData['resourceValidations'] = [];
     for (const config of data.configs) {

src/plugin/plugin.ts

@@ -276,26 +276,51 @@ export class ResourceController<T extends StringIndexedObject> {
       throw new Error(`Type: ${this.typeId} cannot be imported`);
     }
 
-    const context: RefreshContext<T> = {
-      commandType: 'import',
-      isStateful: true,
-      originalDesiredConfig: structuredClone(parameters),
-    };
-
     // Auto search means that no required parameters will be provided. We will try to generate it ourselves or return an
     // empty array if they can't be.
     if (autoSearchAll && this.settings.allowMultiple) {
-      if (this.settings.allowMultiple === true || !this.settings.allowMultiple.findAllParameters?.()) {
-        return [];
-      }
+      return this.findInstances(core);
+    }
 
-      const parametersToImport = await this.settings.allowMultiple.findAllParameters?.();
-      const results = await Promise.all(parametersToImport.map((p) =>
-        this.import(core, p).catch(() => null))
-      );
-      return results.filter(Boolean).flat() as ResourceJson[];
+    return this.refreshForImport(core, parameters);
+  }
+
+  /**
+   * Find every instance of this resource that currently exists on the system using
+   * {@link ResourceSettings.allowMultiple.findAllParameters}. Each instance is refreshed so only instances that
+   * actually exist are returned.
+   *
+   * Unlike {@link import}, this is discovery only and is not blocked by `importAndDestroy.preventImport` (ex: destroy
+   * uses it to let the user pick which instance to remove). Returns an empty array if the resource doesn't support
+   * multiple instances or can't discover them.
+   *
+   * @param core The core config (type, name) to attach to each instance found
+   * @returns Every instance found on the system
+   */
+  async findInstances(core: ResourceConfig): Promise<Array<ResourceJson>> {
+    const { allowMultiple } = this.settings;
+    if (!allowMultiple || allowMultiple === true || !allowMultiple.findAllParameters) {
+      return [];
     }
 
+    const parametersToFind = await allowMultiple.findAllParameters();
+    const results = await Promise.all(parametersToFind.map((p) =>
+      this.refreshForImport(core, p).catch(() => null))
+    );
+
+    return results.filter(Boolean).flat() as ResourceJson[];
+  }
+
+  private async refreshForImport(
+    core: ResourceConfig,
+    parameters: Partial<T>,
+  ): Promise<Array<ResourceJson>> {
+    const context: RefreshContext<T> = {
+      commandType: 'import',
+      isStateful: true,
+      originalDesiredConfig: structuredClone(parameters),
+    };
+
     this.addDefaultValues(parameters);
     await this.applyTransformations(parameters);
 

src/resource/resource-controller.ts

@@ -156,9 +156,23 @@ export interface ResourceSettings<T extends StringIndexedObject> {
      * resource valid for imports. Defaults to false.
      *
      * Resources that can't be imported in the core library for example are: action resources
+     *
+     * Only use this for resources that truly can't be imported. If the resource conflicts with another resource during
+     * import all (ex: `alias` and `aliases` manage the same state) use {@link supersededBy} instead.
      */
     preventImport?: boolean;
 
+    /**
+     * The type id of another resource that manages the same system state as this one, typically the plural version of
+     * this resource (ex: `alias` is superseded by `aliases`, `git-repository` by `git-repositories`).
+     *
+     * When both resources are imported automatically (`codify init` / `codify import` with no arguments), this resource
+     * is skipped so the same state isn't imported twice. It can still be imported directly (`codify import alias`),
+     * planned, applied and destroyed, and its instances can still be discovered with
+     * {@link allowMultiple.findAllParameters}.
+     */
+    supersededBy?: string;
+
     /**
      * Can this resources be destroyed? If set to false then the codifyCLI will skip over/not consider this
      * resource valid for destroys. Defaults to false.