@alienplatform/testing 0.1.0 → 1.3.3

package/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, Apache 2.0 Future License
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2026 Alien Software, Inc.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -1,320 +1,107 @@
 # @alienplatform/testing
 
-Testing framework for Alien applications. Deploy, test, and tear down Alien apps in real environments.
+Testing framework for Alien applications.
 
-## Installation
+## Install
 
 ```bash
-npm install @alienplatform/testing
+npm install --save-dev @alienplatform/testing
 ```
 
-## Quick Start
+## Local vs Cloud
 
-```typescript
-import { deploy } from "@alienplatform/testing"
-
-const deployment = await deploy({
-  app: "./my-app",
-  platform: "aws",
-  workspace: "my-workspace",
-  project: "my-project",
-})
-
-// Test your deployment
-const response = await fetch(`${deployment.url}/api/test`)
-expect(response.status).toBe(200)
+This package has two deployment modes:
 
-// Cleanup
-await deployment.destroy()
-```
-
-## Authentication
-
-### API Key
-
-Set your Alien API key:
-
-```bash
-export ALIEN_API_KEY="your-key"
-# or
-alien login
-```
+- local mode uses `alien dev`
+- cloud mode uses the platform API
 
-### Platform Credentials
+That split is intentional. Local mode stays centered on the shipped `alien` CLI binary instead of asking users to discover lower-level manager binaries.
 
-Credentials are **optional**. When not provided, deployers use standard environment variables.
+## Local Mode
 
-#### AWS
-```bash
-export AWS_ACCESS_KEY_ID="..."
-export AWS_SECRET_ACCESS_KEY="..."
-export AWS_REGION="us-east-1"
-```
+Local mode is the default:
 
-Or pass explicitly:
 ```typescript
-credentials: {
-  platform: "aws",
-  accessKeyId: "...",
-  secretAccessKey: "...",
-  region: "us-east-1",
-}
-```
+import { afterAll, beforeAll, describe, expect, it } from "vitest"
+import { deploy, type Deployment } from "@alienplatform/testing"
 
-#### GCP
-```bash
-export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"
-export GCP_PROJECT_ID="my-project"
-```
+describe("My App", () => {
+  let deployment: Deployment
 
-Or pass explicitly:
-```typescript
-credentials: {
-  platform: "gcp",
-  projectId: "my-project",
-  serviceAccountKeyPath: "/path/to/key.json",
-  // or
-  serviceAccountKeyJson: "{ ... }",
-}
-```
+  beforeAll(async () => {
+    deployment = await deploy({ app: "./my-app" })
+  }, 300_000)
 
-#### Azure
-```bash
-export AZURE_SUBSCRIPTION_ID="..."
-export AZURE_TENANT_ID="..."
-export AZURE_CLIENT_ID="..."
-export AZURE_CLIENT_SECRET="..."
-```
+  afterAll(async () => {
+    await deployment?.destroy()
+  })
 
-Or pass explicitly:
-```typescript
-credentials: {
-  platform: "azure",
-  subscriptionId: "...",
-  tenantId: "...",
-  clientId: "...",
-  clientSecret: "...",
-}
-```
-
-#### Kubernetes
-```bash
-export KUBECONFIG="~/.kube/config"
-```
-
-Or pass explicitly:
-```typescript
-credentials: {
-  platform: "kubernetes",
-  kubeconfigPath: "~/.kube/config",
-}
-```
-
-## Deployment Methods
-
-### API (Default)
-
-Fastest method. Agent Manager deploys directly:
-
-```typescript
-const deployment = await deploy({
-  app: "./my-app",
-  platform: "aws",
-  workspace: "my-workspace",
-  project: "my-project",
-  method: "api", // default
+  it("responds to requests", async () => {
+    const response = await fetch(`${deployment.url}/api/hello`)
+    expect(response.status).toBe(200)
+  })
 })
 ```
 
-### CLI
+Under the hood the package:
 
-Tests the actual CLI deployment flow:
+1. finds the `alien` binary
+2. spawns `alien dev --status-file ...`
+3. waits for the status file to report readiness
+4. reads the public URL and commands URL from that file
 
-```typescript
-const deployment = await deploy({
-  app: "./my-app",
-  platform: "aws",
-  workspace: "my-workspace",
-  project: "my-project",
-  method: "cli",
-})
-```
+The local machine contract is the `DevStatus` JSON written by `alien dev`, not terminal output.
 
-### Terraform
+## Cloud Mode
 
-Tests Terraform provider:
+Cloud mode targets real infrastructure:
 
 ```typescript
 const deployment = await deploy({
   app: "./my-app",
   platform: "aws",
-  workspace: "my-workspace",
-  project: "my-project",
-  method: "terraform",
 })
 ```
 
-### CloudFormation
+Supported cloud platforms:
 
-Tests CloudFormation deployment (AWS only):
+- `aws`
+- `gcp`
+- `azure`
 
-```typescript
-const deployment = await deploy({
-  app: "./my-app",
-  platform: "aws",
-  workspace: "my-workspace",
-  project: "my-project",
-  method: "cloudformation",
-})
-```
-
-### Helm
-
-Tests Helm chart deployment (Kubernetes only):
-
-```typescript
-const deployment = await deploy({
-  app: "./my-app",
-  platform: "kubernetes",
-  workspace: "my-workspace",
-  project: "my-project",
-  method: "helm",
-  valuesYaml: "./values.yaml",
-  namespace: "default",
-})
-```
+Cloud mode requires `ALIEN_API_KEY`.
 
-### Operator Image
-
-Tests pull-mode deployment via Docker operator:
+## API
 
 ```typescript
-const deployment = await deploy({
-  app: "./my-app",
-  platform: "aws",
-  workspace: "my-workspace",
-  project: "my-project",
-  method: "operator-image",
-})
-```
-
-## Query Logs
-
-Query deployment logs using DeepStore:
-
-```typescript
-const deployment = await deploy({
-  app: "./my-app",
-  platform: "test",
-  workspace: "my-workspace",
-  project: "my-project",
-})
-
-// Configure log querying
-const logsConfig = {
-  managerUrl: "http://localhost:3000",
-  deepstoreServerUrl: "http://localhost:8080",
-  databaseId: "db_123",
-  agentToken: "token_123",
+interface DeployOptions {
+  app: string
+  platform?: "local" | "aws" | "gcp" | "azure"
+  config?: string
+  environmentVariables?: EnvironmentVariable[]
+  verbose?: boolean
 }
-
-const logs = await deployment.queryLogs({
-  query: "level:ERROR",
-  startTime: new Date(Date.now() - 3600_000), // 1 hour ago
-  endTime: new Date(),
-  maxHits: 100,
-})
-
-console.log(`Found ${logs.num_hits} logs`)
-```
-
-## Environment Variables
-
-Pass environment variables to your deployment:
-
-```typescript
-const deployment = await deploy({
-  app: "./my-app",
-  platform: "aws",
-  workspace: "my-workspace",
-  project: "my-project",
-  environmentVariables: [
-    { name: "DATABASE_URL", value: "postgres://...", type: "plaintext" },
-    { name: "API_KEY", value: "secret", type: "secret" },
-  ],
-})
 ```
 
-## Stack Settings
-
-Customize deployment behavior:
-
-```typescript
-const deployment = await deploy({
-  app: "./my-app",
-  platform: "aws",
-  workspace: "my-workspace",
-  project: "my-project",
-  stackSettings: {
-    deploymentModel: "push",
-    heartbeats: "on",
-    telemetry: "auto",
-    updates: "auto",
-  },
-})
-```
-
-## Example Test
-
-```typescript
-import { describe, it, expect } from "vitest"
-import { deploy } from "@alienplatform/testing"
-
-describe("my app", () => {
-  it("should deploy and respond", async () => {
-    const deployment = await deploy({
-      app: "./fixtures/my-app",
-      platform: "test",
-      workspace: "test-workspace",
-      project: "test-project",
-    })
-
-    try {
-      const response = await fetch(`${deployment.url}/api/hello`)
-      const data = await response.json()
-      
-      expect(response.status).toBe(200)
-      expect(data.message).toBe("Hello, World!")
-    } finally {
-      await deployment.destroy()
-    }
-  }, 180_000) // 3 min timeout
-})
-```
-
-## API Reference
-
-### `deploy(options: DeployOptions): Promise<Deployment>`
-
-Deploy an Alien application for testing.
-
-### `Deployment`
+The returned `Deployment` supports:
 
-Handle to a deployed application.
+- `deployment.url`
+- `deployment.invokeCommand(name, params)`
+- `deployment.setExternalSecret(vault, key, value)`
+- `deployment.upgrade(options)` for cloud mode
+- `deployment.destroy()`
 
-**Properties:**
-- `id: string` - Agent ID
-- `name: string` - Agent name
-- `url: string` - Deployment URL
-- `platform: Platform` - Target platform
-- `status: AgentStatus` - Current status
+## Configuration
 
-**Methods:**
-- `refresh(): Promise<void>` - Refresh deployment info from API
-- `waitForStatus(status: AgentStatus, options?: WaitOptions): Promise<void>` - Wait for specific status
-- `queryLogs(query: LogQuery): Promise<LogQueryResult>` - Query deployment logs
-- `destroy(): Promise<void>` - Tear down the deployment
+| Variable | Description | Default |
+|---|---|---|
+| `ALIEN_API_KEY` | Platform API key for cloud mode | — |
+| `ALIEN_API_URL` | Platform API base URL | `https://api.alien.dev` |
+| `ALIEN_CLI_PATH` | Path to the `alien` binary | auto-detected |
+| `VERBOSE` | Show detailed child-process logs | `false` |
 
-## License
+## Notes
 
-ISC
+- local mode needs only the `alien` binary
+- cloud mode needs `ALIEN_API_KEY`
+- repo-internal low-level tests can still use standalone manager helpers directly; this package is the higher-level product-facing layer

package/dist/errors.js

@@ -0,0 +1,37 @@
+import { AlienError, defineError } from "@alienplatform/core";
+import * as z from "zod/v4";
+//#region src/errors.ts
+const TestingOperationFailedError = defineError({
+	code: "TESTING_OPERATION_FAILED",
+	context: z.object({
+		operation: z.string(),
+		message: z.string(),
+		details: z.record(z.string(), z.unknown()).optional()
+	}),
+	message: ({ operation, message }) => `Testing operation '${operation}' failed: ${message}`,
+	retryable: false,
+	internal: false,
+	httpStatusCode: 500
+});
+const TestingUnsupportedPlatformError = defineError({
+	code: "TESTING_UNSUPPORTED_PLATFORM",
+	context: z.object({
+		platform: z.string(),
+		operation: z.string()
+	}),
+	message: ({ platform, operation }) => `Unsupported platform '${platform}' for testing operation '${operation}'`,
+	retryable: false,
+	internal: false,
+	httpStatusCode: 400
+});
+async function withTestingContext(error, operation, message, details) {
+	return (await AlienError.from(error)).withContext(TestingOperationFailedError.create({
+		operation,
+		message,
+		details
+	}));
+}
+//#endregion
+export { TestingUnsupportedPlatformError as n, withTestingContext as r, TestingOperationFailedError as t };
+
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["import { AlienError, defineError } from \"@alienplatform/core\"\nimport * as z from \"zod/v4\"\n\nexport const TestingOperationFailedError = defineError({\n  code: \"TESTING_OPERATION_FAILED\",\n  context: z.object({\n    operation: z.string(),\n    message: z.string(),\n    details: z.record(z.string(), z.unknown()).optional(),\n  }),\n  message: ({ operation, message }) => `Testing operation '${operation}' failed: ${message}`,\n  retryable: false,\n  internal: false,\n  httpStatusCode: 500,\n})\n\nexport const TestingUnsupportedPlatformError = defineError({\n  code: \"TESTING_UNSUPPORTED_PLATFORM\",\n  context: z.object({\n    platform: z.string(),\n    operation: z.string(),\n  }),\n  message: ({ platform, operation }) =>\n    `Unsupported platform '${platform}' for testing operation '${operation}'`,\n  retryable: false,\n  internal: false,\n  httpStatusCode: 400,\n})\n\nexport async function withTestingContext(\n  error: unknown,\n  operation: string,\n  message: string,\n  details?: Record<string, unknown>,\n): Promise<AlienError<any>> {\n  return (await AlienError.from(error)).withContext(\n    TestingOperationFailedError.create({\n      operation,\n      message,\n      details,\n    }),\n  )\n}\n"],"mappings":";;;AAGA,MAAa,8BAA8B,YAAY;CACrD,MAAM;CACN,SAAS,EAAE,OAAO;EAChB,WAAW,EAAE,QAAQ;EACrB,SAAS,EAAE,QAAQ;EACnB,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,SAAS,CAAC,CAAC,UAAU;EACtD,CAAC;CACF,UAAU,EAAE,WAAW,cAAc,sBAAsB,UAAU,YAAY;CACjF,WAAW;CACX,UAAU;CACV,gBAAgB;CACjB,CAAC;AAEF,MAAa,kCAAkC,YAAY;CACzD,MAAM;CACN,SAAS,EAAE,OAAO;EAChB,UAAU,EAAE,QAAQ;EACpB,WAAW,EAAE,QAAQ;EACtB,CAAC;CACF,UAAU,EAAE,UAAU,gBACpB,yBAAyB,SAAS,2BAA2B,UAAU;CACzE,WAAW;CACX,UAAU;CACV,gBAAgB;CACjB,CAAC;AAEF,eAAsB,mBACpB,OACA,WACA,SACA,SAC0B;AAC1B,SAAQ,MAAM,WAAW,KAAK,MAAM,EAAE,YACpC,4BAA4B,OAAO;EACjC;EACA;EACA;EACD,CAAC,CACH"}

package/dist/external-secrets.js

@@ -0,0 +1,140 @@
+import { n as TestingUnsupportedPlatformError, r as withTestingContext, t as TestingOperationFailedError } from "./errors.js";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { AlienError } from "@alienplatform/core";
+import { PutParameterCommand, SSMClient } from "@aws-sdk/client-ssm";
+import { ClientSecretCredential } from "@azure/identity";
+import { SecretClient } from "@azure/keyvault-secrets";
+import { SecretManagerServiceClient } from "@google-cloud/secret-manager";
+//#region src/external-secrets.ts
+/**
+* External secrets - platform-native secret management
+*/
+/**
+* Set an external secret using platform-native tools
+*
+* Falls back to environment variables for cloud provider credentials.
+*/
+async function setExternalSecret(platform, resourcePrefix, vaultName, secretKey, secretValue, _namespace, stateDir, deploymentId) {
+	try {
+		switch (platform) {
+			case "aws":
+				await setAWSSecret(resourcePrefix, vaultName, secretKey, secretValue);
+				break;
+			case "gcp":
+				await setGCPSecret(resourcePrefix, vaultName, secretKey, secretValue);
+				break;
+			case "azure":
+				await setAzureSecret(resourcePrefix, vaultName, secretKey, secretValue);
+				break;
+			case "local":
+				await setLocalSecret(vaultName, secretKey, secretValue, stateDir, deploymentId);
+				break;
+			default: {
+				const exhaustive = platform;
+				throw new AlienError(TestingUnsupportedPlatformError.create({
+					platform: String(exhaustive),
+					operation: "setExternalSecret"
+				}));
+			}
+		}
+	} catch (error) {
+		throw await withTestingContext(error, "setExternalSecret", "Failed to set external secret", {
+			platform,
+			resourcePrefix,
+			vaultName,
+			secretKey
+		});
+	}
+}
+/**
+* Set AWS SSM Parameter Store secret
+*
+* Uses environment variables for credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION).
+*/
+async function setAWSSecret(resourcePrefix, vaultName, secretKey, secretValue) {
+	const client = new SSMClient({ region: process.env.AWS_REGION });
+	const parameterName = `/${resourcePrefix}-${vaultName}-${secretKey}`;
+	await client.send(new PutParameterCommand({
+		Name: parameterName,
+		Value: secretValue,
+		Type: "SecureString",
+		Overwrite: true
+	}));
+}
+/**
+* Set GCP Secret Manager secret
+*
+* Uses environment variables for credentials (GOOGLE_APPLICATION_CREDENTIALS, GCP_PROJECT_ID).
+*/
+async function setGCPSecret(resourcePrefix, vaultName, secretKey, secretValue) {
+	const client = new SecretManagerServiceClient();
+	const projectId = process.env.GCP_PROJECT_ID || process.env.GOOGLE_CLOUD_PROJECT;
+	if (!projectId) throw new AlienError(TestingOperationFailedError.create({
+		operation: "setGCPSecret",
+		message: "GCP project ID is required (set GCP_PROJECT_ID or GOOGLE_CLOUD_PROJECT env var)"
+	}));
+	const secretName = `${resourcePrefix}-${vaultName}-${secretKey}`;
+	const parent = `projects/${projectId}`;
+	const secretPath = `${parent}/secrets/${secretName}`;
+	try {
+		await client.createSecret({
+			parent,
+			secretId: secretName,
+			secret: { replication: { automatic: {} } }
+		});
+	} catch (error) {
+		if (!error.message?.includes("ALREADY_EXISTS")) throw await withTestingContext(error, "setGCPSecret", "Failed to create GCP secret");
+	}
+	await client.addSecretVersion({
+		parent: secretPath,
+		payload: { data: Buffer.from(secretValue, "utf8") }
+	});
+}
+/**
+* Set Azure Key Vault secret
+*
+* Uses environment variables for credentials (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET).
+*/
+async function setAzureSecret(resourcePrefix, vaultName, secretKey, secretValue) {
+	const vaultUrl = `https://${`${resourcePrefix}-${vaultName}`}.vault.azure.net`;
+	const tenantId = process.env.AZURE_TENANT_ID;
+	const clientId = process.env.AZURE_CLIENT_ID;
+	const clientSecret = process.env.AZURE_CLIENT_SECRET;
+	if (!tenantId || !clientId || !clientSecret) throw new AlienError(TestingOperationFailedError.create({
+		operation: "setAzureSecret",
+		message: "Azure credentials are required (set AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET env vars)"
+	}));
+	const client = new SecretClient(vaultUrl, new ClientSecretCredential(tenantId, clientId, clientSecret));
+	const azureSecretKey = secretKey.replace(/_/g, "-");
+	await client.setSecret(azureSecretKey, secretValue);
+}
+/**
+* Set local dev secret by writing directly to the vault's secrets.json file.
+*
+* The local vault binding (LocalVault) reads from:
+*   {stateDir}/{deploymentId}/vault/{vaultName}/secrets.json
+*
+* We write to the same path so the running function can read it immediately.
+*/
+async function setLocalSecret(vaultName, secretKey, secretValue, stateDir, deploymentId) {
+	if (!stateDir) throw new AlienError(TestingOperationFailedError.create({
+		operation: "setLocalSecret",
+		message: "stateDir is required for local vault set"
+	}));
+	if (!deploymentId) throw new AlienError(TestingOperationFailedError.create({
+		operation: "setLocalSecret",
+		message: "deploymentId is required for local vault set"
+	}));
+	const vaultDir = join(stateDir, deploymentId, "vault", vaultName);
+	const secretsFile = join(vaultDir, "secrets.json");
+	let secrets = {};
+	if (existsSync(secretsFile)) secrets = JSON.parse(readFileSync(secretsFile, "utf-8"));
+	secrets[secretKey] = secretValue;
+	mkdirSync(vaultDir, { recursive: true });
+	writeFileSync(secretsFile, JSON.stringify(secrets, null, 2));
+}
+//#endregion
+export { setExternalSecret };
+
+//# sourceMappingURL=external-secrets.js.map