@fntio/infra-client-plugin-cdk 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# @fntio/infra-client-plugin-cdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Registers customer plugins from an existing CDK application. This package holds
+`definePlugin`, the synth-time validation of a definition; the constructs that create the
+gateway methods, upload the assets and write the catalog record (`resolvePlugins`,
+`PluginApi`, `PluginCatalogActivation`) live in `@fntio/infra-client` and run when the
+definition is passed to `addAccessPortal` — see the core README's
+[Plugins](../infra-client/README.md#plugins) section. Private until publishing is enabled.
+
+## `definePlugin`
+
+Turns a customer's definition into a validated `PluginDefinition`: the serializable
+manifest (what the catalog stores and the portal discovers) separated from the
+deployment inputs (the asset directory and the Lambda handlers).
+
+```ts
+import { definePlugin } from "@fntio/infra-client-plugin-cdk";
+
+export const parameters = definePlugin({
+  schemaVersion: 1,
+  id: "parameters",
+  displayName: "Application parameters",
+  version: "1.0.0",
+  hostApiVersion: 1,
+  enabled: true,
+  accounts: [{ accountNumber: "123456789012", regions: ["eu-central-1"] }],
+  permissions: [
+    { id: "user", label: "View application parameters" },
+    { id: "admin", label: "Edit application parameters" },
+  ],
+  ui: {
+    assets: "./plugins/parameters/dist",
+    user: { label: "Parameters", entry: "index.html#/user" },
+    admin: { label: "Parameters", entry: "index.html#/admin" },
+  },
+  backend: {
+    handlers: { api: (scope) => new lambda.Function(scope, "ParametersApi", { /* ... */ }) },
+    routes: [
+      { id: "list", method: "GET", path: "/parameters", permission: "user", handlerKey: "api" },
+      { id: "update", method: "PUT", path: "/parameters/{name}", permission: "admin", handlerKey: "api" },
+    ],
+  },
+});
+```
+
+A handler is either an existing `IFunction` or a factory that the registration
+construct calls once inside its own scope. `ui.assets` resolves like a CDK asset
+path, from the process working directory.
+
+`definePlugin` throws one `PluginValidationError` listing every problem: the SDK's
+manifest rules (see the SDK README), plus routes naming a handler key that has no
+handler, a missing asset directory, and an entry file that is not in it. It runs at
+synth time, so a bad definition fails `cdk synth`, never a deploy.
+
+## Develop
+
+```
+cd packages/infra-client-plugin-cdk
+npx tsc --noEmit && npm test
+```
+
+Type checks and tests resolve `@fntio/infra-client-plugin-sdk` to its `src/`
+(tsconfig `paths` + Jest `moduleNameMapper`); `npm run build` uses the SDK's built
+`dist/`, so run `npm run build:plugins` at the repository root to build all three.
+
+## Agent skill
+
+`skills/integrate-infra-client-plugin/` ships with this package: it inspects an existing CDK
+application's own conventions — where the portal is composed, how Lambdas are built, how it deploys —
+and makes the smallest correct change, then diffs it. Make it available the way your agent setup
+already does; there is no installer and no generated project.
+
+## The lifecycle in one place
+
+| Step | What to change | What happens |
+| --- | --- | --- |
+| Install | add the definition to `plugins` | assets upload, routes mount, a catalog record is written |
+| Update | change the definition | a new revision; a running frame prompts to reload |
+| Rollback | redeploy the previous definition | the record returns through the same provider |
+| Disable | `enabled: false` | hidden and refused; grants stay, dormant and revocable |
+| Remove | delete the registration | record tombstoned before the routes go; grants deliberately kept |
+| Reinstall | add the same id back | still-valid grants come back with it |
+
+Removing the registrations and turning the whole feature off are two separate deploys, in that order.
+
+A worked example of everything above is [`@fntio/infra-client-plugin-example`](../infra-client-plugin-example/README.md).

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import type { IFunction } from "aws-cdk-lib/aws-lambda";
+import type { Construct } from "constructs";
+import { PluginAccountBinding, PluginManifestV1, PluginPermissionDefinition, PluginRoute, PluginUiEntry } from "@fntio/infra-client-plugin-sdk";
+export { PluginValidationError } from "@fntio/infra-client-plugin-sdk";
+export type { PluginManifestV1, PluginRoute, PluginUiEntry } from "@fntio/infra-client-plugin-sdk";
+/** An existing function, or a factory the registration construct calls once inside its own scope. */
+export type PluginHandlerSource = IFunction | ((scope: Construct) => IFunction);
+export interface PluginUiDefinition {
+    /** Built frontend directory (relative paths resolve from the process working directory, like CDK assets). */
+    readonly assets: string;
+    readonly user?: PluginUiEntry;
+    readonly admin?: PluginUiEntry;
+}
+export interface PluginBackendDefinition {
+    /** Keyed by the `handlerKey` routes refer to. */
+    readonly handlers: Readonly<Record<string, PluginHandlerSource>>;
+    readonly routes: readonly PluginRoute[];
+}
+/** What a customer writes: the manifest fields plus deployment inputs (assets, handlers). */
+export interface PluginDefinitionInput {
+    readonly schemaVersion: 1;
+    readonly id: string;
+    readonly displayName: string;
+    readonly description?: string;
+    readonly version: string;
+    readonly hostApiVersion: 1;
+    readonly enabled: boolean;
+    readonly accounts: readonly PluginAccountBinding[];
+    readonly permissions: readonly PluginPermissionDefinition[];
+    readonly ui?: PluginUiDefinition;
+    readonly backend?: PluginBackendDefinition;
+}
+/** A validated definition: the serializable manifest, separated from the deployment-only inputs. */
+export interface PluginDefinition {
+    readonly manifest: PluginManifestV1;
+    /** Absolute path of the asset directory; absent for backend-only plugins. */
+    readonly assetDirectory?: string;
+    readonly handlers: Readonly<Record<string, PluginHandlerSource>>;
+}
+export declare function definePlugin(input: PluginDefinitionInput): PluginDefinition;

package/dist/index.js

@@ -0,0 +1,77 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginValidationError = void 0;
+exports.definePlugin = definePlugin;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const infra_client_plugin_sdk_1 = require("@fntio/infra-client-plugin-sdk");
+var infra_client_plugin_sdk_2 = require("@fntio/infra-client-plugin-sdk");
+Object.defineProperty(exports, "PluginValidationError", { enumerable: true, get: function () { return infra_client_plugin_sdk_2.PluginValidationError; } });
+function definePlugin(input) {
+    const { ui, backend, ...fields } = input;
+    const handlers = backend?.handlers ?? {};
+    const manifestInput = { ...fields, routes: backend?.routes ?? [] };
+    if (ui !== undefined) {
+        manifestInput.ui = {
+            ...(ui.user === undefined ? {} : { user: ui.user }),
+            ...(ui.admin === undefined ? {} : { admin: ui.admin }),
+        };
+    }
+    const manifest = (0, infra_client_plugin_sdk_1.assertPluginManifest)(manifestInput, { handlerKeys: Object.keys(handlers) });
+    const assetDirectory = ui === undefined ? undefined : resolveAssetDirectory(ui.assets, manifest);
+    return { manifest, assetDirectory, handlers };
+}
+function resolveAssetDirectory(assets, manifest) {
+    const dir = path.resolve(assets);
+    const issues = [];
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+        issues.push({ code: "ui-assets-directory", path: "ui.assets", message: `${dir} is not a directory (build the plugin frontend first?)` });
+    }
+    else {
+        for (const kind of ["user", "admin"]) {
+            const entry = manifest.ui?.[kind];
+            if (!entry)
+                continue;
+            const file = path.resolve(dir, (0, infra_client_plugin_sdk_1.pluginEntryFile)(entry.entry));
+            if (!file.startsWith(dir + path.sep) || !fs.existsSync(file) || !fs.statSync(file).isFile()) {
+                issues.push({ code: "ui-entry-missing", path: `ui.${kind}.entry`, message: `${(0, infra_client_plugin_sdk_1.pluginEntryFile)(entry.entry)} not found under ${dir}` });
+            }
+        }
+    }
+    if (issues.length > 0)
+        throw new infra_client_plugin_sdk_1.PluginValidationError(issues, `Plugin "${manifest.id}"`);
+    return dir;
+}

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@fntio/infra-client-plugin-cdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Define and register infra-client customer plugins from an existing CDK application.",
+  "license": "Elastic-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/FNTIO/aws-infrastructure-client.git",
+    "directory": "packages/infra-client-plugin-cdk"
+  },
+  "homepage": "https://github.com/FNTIO/aws-infrastructure-client/wiki",
+  "bugs": {
+    "url": "https://github.com/FNTIO/aws-infrastructure-client/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "test": "jest"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "roots": [
+      "<rootDir>/src"
+    ],
+    "testMatch": [
+      "**/*.test.ts"
+    ],
+    "transform": {
+      "^.+\\.tsx?$": [
+        "ts-jest",
+        {
+          "tsconfig": "<rootDir>/tsconfig.jest.json"
+        }
+      ]
+    },
+    "moduleNameMapper": {
+      "^@fntio/infra-client-plugin-sdk$": "<rootDir>/../infra-client-plugin-sdk/src/index.ts",
+      "^@fntio/infra-client-plugin-sdk/(.*)$": "<rootDir>/../infra-client-plugin-sdk/src/$1/index.ts"
+    },
+    "maxWorkers": "50%",
+    "workerIdleMemoryLimit": "2GB"
+  },
+  "dependencies": {
+    "@fntio/infra-client-plugin-sdk": "^0.2.0"
+  },
+  "peerDependencies": {
+    "aws-cdk-lib": "^2.263.0",
+    "constructs": "^10.3.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.19.43",
+    "aws-cdk-lib": "2.263.0",
+    "constructs": "10.6.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.0",
+    "typescript": "^5.5.0"
+  }
+}

package/skills/integrate-infra-client-plugin/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: integrate-infra-client-plugin
+description: Add an existing infra-client plugin to a CDK application that already exists — registration, asset build, IAM, and the deploy, update, rollback, disable and remove lifecycle. Use when someone asks to install, register, upgrade or remove a portal plugin in their infrastructure.
+---
+
+# Integrate a plugin into an existing CDK application
+
+This is infrastructure work on a codebase someone already owns and deploys. The goal is the smallest
+correct change to their existing app — not a new project, not a new pipeline, not a restructure.
+
+**Read the installed package's documentation first** — `README.md` in `@fntio/infra-client-plugin-cdk`
+and the `Plugins` section of `@fntio/infra-client`'s README. They describe the version installed here.
+
+## Inspect before you change anything
+
+1. **Find where the portal is composed.** Either `addAccessPortal(...)`, or the stacks composed by
+   hand. The plugin list goes wherever that call already is.
+2. **Find their Lambda conventions** — construct, bundler, runtime, log retention — and their asset
+   build. A plugin's handler and frontend should be built the way everything else here is built.
+3. **Find their deployment path.** A pipeline, a workflow, a manual command. The plugin's frontend
+   must be built before synth, so that build belongs wherever their other build steps already are.
+4. **Check the feature is on.** Plugins need the `plugins` block enabled in the project config.
+   Registering one while the feature is off fails at synth, on purpose.
+
+## Make the change
+
+- Add the registration to the existing plugin list. Do not create a stack for it unless the project's
+  own conventions call for one.
+- Keep construct ids stable. Renaming one replaces resources.
+- Scope the handler's IAM to exactly what it needs, in the project's usual style.
+- Then synthesize and **diff against the deployed state**. Expect: the plugin's methods, its authorizer
+  if this is the first plugin with routes, an asset upload, and a catalog record. Anything else
+  appearing — especially a changed identity on an unrelated resource — means something moved that
+  should not have.
+
+## The lifecycle, and what each step does
+
+- **Update**: change the definition, redeploy. A new revision is recorded; a running frame prompts the
+  user to reload rather than being swapped out.
+- **Rollback**: redeploy the previous definition. The record returns through the same provider.
+- **Disable**: `enabled: false` keeps everything but hides the plugin and refuses its calls. Grants
+  stay, visible and dormant.
+- **Remove**: delete the registration. The record is tombstoned before the routes go, holders are
+  notified, and grant rows are deliberately kept so reinstalling the same id restores still-valid
+  access.
+- **Turn the whole feature off**: remove the registrations first, in their own deploy, then disable the
+  feature. Doing both at once can fail on an export still in use.
+
+## Hand back
+
+State plainly what the diff contained, what a deploy will do to existing grants, and which steps are
+manual. If anything the customer must decide is missing — which accounts, which prefixes, which
+execution role — ask rather than inventing a value.