@sl-testing/ac-pulumi 0.1.29 → 0.1.31

package/README.md

@@ -0,0 +1,82 @@
+# Infra Pulumi Provider
+
+# Spec
+- Export surface: `@sl-testing/ac-pulumi`.
+- Purpose: own the custom Pulumi provider source, provider schema, generated Node SDK distribution, plugin packaging, and install-time plugin bootstrap.
+- Owns: `core/infra-pulumi-provider/provider`, `core/infra-pulumi-provider/postinstall.js`, generated SDK artifacts under `dist`, provider schema/codegen inputs, and release packaging logic for the published Pulumi package.
+- Does not own: Terraform env roots, platform API behavior, or product resource semantics beyond faithfully exposing the platform contract.
+- Dependencies: resource semantics come from `core/api/AGENTS.md` and the owning domain module `AGENTS.md` files.
+- Cross-module contract: consumers import provider resources only from the package root `@sl-testing/ac-pulumi`.
+- Provider package contract:
+  - this module ships the `agentcloud` Pulumi resource provider plus the generated Node SDK published as `@sl-testing/ac-pulumi`
+  - provider source-of-truth lives in `provider/*.go`; checked-in `dist` output is generated, not hand-edited
+  - release packaging runs through `core/repo-tools/src/build-ac-pulumi-package.sh`, injects `main.providerVersion`, runs `pulumi package gen-sdk`, patches the generated Node wrapper, and bundles provider binaries plus `postinstall.js`
+  - published installs auto-attempt `pulumi plugin install resource agentcloud <version> --reinstall` from the packaged binary, but do not hard-fail npm install if Pulumi or the plugin install step is unavailable
+  - bundled plugin binaries currently target `darwin-arm64` and `linux-x64`
+- Provider scope and config:
+  - the provider manages project-owned resources inside one existing project at a time
+  - provider config keys are `agentcloud:apiUrl` and `agentcloud:projectId`
+  - resource `projectId` may override provider config per resource; reads prefer explicit `projectId`, then the compound import ID, then provider config
+  - `agentcloud:apiUrl` may come from Pulumi config or `AC_API_URL`; `projectId` must come from Pulumi config or resource input, not an env fallback
+  - previews synthesize placeholder canonical IDs with zero suffixes until the API returns the real resource ID
+  - project-owned import IDs use `<projectId>/<resource_type>/<resource_id>`
+  - the provider does not use workspace-era identifiers in the product contract
+- Provider connectivity and auth:
+  - `agentcloud infra init` persists `agentcloud:projectId` and `agentcloud:environment=prod`, but not `agentcloud:apiUrl`
+  - machine-side `agentcloud infra plan|apply|drift|destroy` uses the canonical remote Pulumi backend for the target stack
+  - `agentcloud infra apply` never implicitly reuses a default saved plan file; saved-plan apply happens only with `--plan-file`
+  - auth resolution order is `AC_BOOTSTRAP_TOKEN` exchange at `POST /v1/runtime-auth/exchange`, then `AC_TOKEN`, then `AC_TOKEN_FILE`, then `AC_SESSION_COOKIE`, then `AC_SESSION_FILE`, then `~/.agentcloud/session.cookie`
+  - `AC_TOKEN_FILE` is bearer-token-only and rejects cookie-form values
+  - `AC_SESSION_FILE` is cookie-only and rejects bearer-token-only values
+- Provider surface:
+- managed resources are `Secret`, `ProjectRole`, `ProjectRoleRule`, `ProjectRoleBinding`, `Database`, `Image`, `Machine`, `AgentConfiguration`, `Job`, `Service`, `ServiceDeploymentResource`, and `SlackConnection`
+  - invoke helpers are `permissionCatalog`, `agentRuns`, `messages`, `jobRuns`, `serviceDeployments`, `imageVersions`, `imageVersionsByImage`, and `logs`
+  - invoke helpers are project-scoped, read-only helpers; lifecycle ownership belongs to resources
+- Resource lifecycle contract:
+  - `Secret`: `key` is immutable; update re-puts the value; reads never fetch plaintext back from the API and preserve the Pulumi-encrypted last-known value in state
+  - `ProjectRole`: `name` is immutable; update patches `description` only
+  - `ProjectRoleRule`: wraps role grants; `roleId` and `permission` are immutable; updates replace rule scope/resource selectors by deleting the old rule and granting a new one; validated rule selectors are limited to canonical product resource types
+  - `ProjectRoleBinding`: binds `subjectType + subjectId + roleId`; valid subject types are `user`, `agent_configuration`, `job`, `service`, and `public`; create de-duplicates by looking up an existing binding on conflict; updates are delete-and-recreate
+  - `Database`: create/read/delete only; `name` is immutable; state stays minimal with `projectId`, `name`, `databaseId`, and `status`; no restore, endpoint metadata, credentials metadata, cluster identifiers, AWS ARNs, or size classes are exposed
+  - `Image`: `name` and `sourceType` are immutable; updates patch `dockerfilePath`, `contextPath`, and `registryRef`; registry-source reads preserve explicit `registryRef` input when needed; delete retries deterministic `409` conflicts briefly before surfacing failure
+  - `Machine`: `name` is immutable; image version, size, and working directory update in place; reads treat `deleted` status as absent
+  - `AgentConfiguration`: this is the durable configuration object, not the runtime agent; `name` and `provider` are immutable; image version, size, working dir, model, Codex thinking, instructions, and idle timeouts update in place
+  - `Job`: `name` is immutable; image version, command, input schema, timeout, and max parallel runs update in place
+  - `Service`: `type` and `name` are immutable; `cpu`, `memoryMb`, `port`, and `healthcheckPath` update in place; reads expose live `status` and `serviceUrl`
+  - `ServiceDeploymentResource`: models service deploy operations, not the service definition; `projectId` and `serviceId` replace, `imageVersionId` replace, create/update call `POST /deploy` and wait up to 10 minutes for a `healthy` deployment, and a matching current healthy deployment is treated as idempotent success; delete is intentionally a no-op and does not rollback
+- There is no standalone Pulumi `Function` resource. Function services expose manifest-backed functions from the deployed image and are managed through the `Service` plus `ServiceDeploymentResource` contract.
+- Replace, import, and error semantics:
+  - default rule is dumb/simple mapping: safe scalar knobs update in place; ownership/identity fields replace
+  - canonical project-scoped import IDs exist for all managed resources; most resources can read/delete from the import ID alone, but `ProjectRoleRule` and `ProjectRoleBinding` currently still rely on state-carried IDs on follow-up read/delete
+  - surfaced provider errors preserve API `error_code`
+  - `400` maps to `InvalidArgument`
+  - `401` and `403` map to `PermissionDenied`
+  - `404` maps to `NotFound`
+  - `409` maps to `FailedPrecondition`
+  - delete treats `NotFound` as success for managed resources
+  - runtime agents are not Pulumi-managed resources
+- Provider generality:
+  - the provider is product-level and project-agnostic
+  - it does not hardcode meta-project names, resource names, service names, or workflow assumptions
+  - it does not ship a `Project` resource and does not manage `projects.main_agent_configuration_id` or `projects.main_agent_id`
+  - project main-agent pointers remain API-managed or userland-managed
+
+# Testing
+- Fast proof: `npm run -w core/infra-pulumi-provider lint`.
+- Provider proof: `(cd core/infra-pulumi-provider/provider && go test ./...)`.
+- SDK proof: rerun `bash core/repo-tools/src/build-ac-pulumi-package.sh --version <version>` when schema/codegen, provider packaging, or plugin bootstrap changes.
+- Install proof: run `bash core/repo-tools/src/smoke-ac-pulumi-npm-install.sh [--version <version>]` for the published package path.
+
+# Deployment
+- Ships as the published Pulumi provider and generated SDK package, not as a long-running runtime.
+- Any provider contract change must be regenerated and republished before meta-project stacks consume it.
+- Keep `package.json`, the Pulumi package metadata, and injected provider binary version aligned across release artifacts.
+
+# Monitoring
+- Watch provider apply/import failures, auth resolution regressions, schema drift, postinstall/plugin install regressions, and generated SDK mismatches against the live API.
+- After release, validate at least one representative Pulumi program still previews and applies.
+
+# Risks
+- Provider drift breaks infrastructure reconciliation and meta-project deployment.
+- Import/read drift is especially risky because Pulumi state adoption depends on canonical compound IDs working consistently.
+- Never patch generated output without updating the underlying provider/schema pipeline.

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@pulumi/agentcloud",
-    "version": "0.1.29",
+    "version": "0.1.31",
     "main": "bin/index.js",
     "scripts": {
         "build": "tsc",
@@ -14,6 +14,6 @@
     "pulumi": {
         "resource": true,
         "name": "agentcloud",
-        "version": "0.1.29"
+        "version": "0.1.31"
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sl-testing/ac-pulumi",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "description": "AgentCloud TypeScript SDK generated from the Pulumi provider schema",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -23,7 +23,7 @@
     "test": "echo 'no tests yet'"
   },
   "dependencies": {
-    "@pulumi/pulumi": "^3.158.0"
+    "@pulumi/pulumi": "3.158.0"
   },
   "agentcloud": {
     "kind": "infra",
@@ -32,6 +32,6 @@
   "pulumi": {
     "resource": true,
     "name": "agentcloud",
-    "version": "0.1.29"
+    "version": "0.1.31"
   }
 }