@stacksjs/config 0.74.37 → 0.74.39

package/dist/capabilities.d.ts

@@ -1,6 +1,10 @@
+/** Whether this driver's behaviour depends on a service this repository does not own. */
+export declare function isRemoteTopology(topology: CapabilityTopology): boolean;
 export declare function capabilityDrivers(category: CapabilityCategory): readonly CapabilityDriver[];
 export declare function findCapability(category: CapabilityCategory, name: string): CapabilityDriver | undefined;
 export declare function assertCapabilityAvailable(category: CapabilityCategory, name: string): CapabilityDriver;
+/** The remote half, as a value, so a check can ask rather than restate it. */
+export declare const REMOTE_TOPOLOGIES: ReadonlySet<CapabilityTopology>;
 export declare const capabilityRegistry: readonly CapabilityDriver[];
 export declare interface CapabilityDriver {
   category: CapabilityCategory
@@ -8,10 +12,38 @@ export declare interface CapabilityDriver {
   status: CapabilityStatus
   implementation: string | null
   testEvidence: string[]
-  topology: string
+  topology: CapabilityTopology
   prerequisites: string[]
   limitations: string[]
   liveServiceContract?: { service: string, version: string, workflow: string }
 }
 export type CapabilityCategory = 'database' | 'queue' | 'cache' | 'storage' | 'mail' | 'realtime' | 'deploy';
 export type CapabilityStatus = 'supported' | 'partial' | 'experimental' | 'unsupported';
+/**
+ * Where a driver's work actually happens.
+ *
+ * A closed vocabulary rather than a free string, for two reasons. A typo in a
+ * free string is invisible - `in-process` and `inprocess` would sit next to
+ * each other in the matrix forever. And the split below is load-bearing:
+ * whether a driver depends on something outside this process decides whether
+ * calling it `supported` requires a versioned provider contract
+ * (stacksjs/stacks#2056).
+ */
+export type CapabilityTopology = LocalTopology | RemoteTopology;
+/** Runs inside this process, or on its filesystem. Nothing to version. */
+export type LocalTopology = | 'embedded'
+  | 'inline'
+  | 'in-process'
+  | 'local-file'
+  | 'local-filesystem'
+  | 'single-process-websocket'
+  | 'worker-and-embedded-sqlite';
+/** Depends on something outside this process, whose version is a fact about the claim. */
+export type RemoteTopology = | 'client-server'
+  | 'managed-service'
+  | 'managed-object-storage'
+  | 'mysql-behind-vtgate'
+  | 'smtp-server'
+  | 'worker-and-redis'
+  | 'hetzner-vm-systemd-rpx'
+  | 'ssh-box-systemd-rpx';

package/dist/capabilities.js

@@ -1 +1 @@
-export const capabilityRegistry=[{category:"database",name:"sqlite",status:"supported",implementation:"storage/framework/core/database/src/drivers/sqlite.ts",testEvidence:["storage/framework/core/database/tests/integration.test.ts","storage/framework/core/database/tests/sqlite-tx-serialization.test.ts"],topology:"embedded",prerequisites:["Bun SQLite"],limitations:[]},{category:"database",name:"mysql",status:"partial",implementation:"storage/framework/core/database/src/drivers/mysql.ts",testEvidence:["storage/framework/core/database/tests/integration.test.ts"],topology:"client-server",prerequisites:["MySQL service"],limitations:["The default CI suite does not yet publish a dedicated dialect report.","The migration files shipped under database/migrations are emitted for a single dialect (SQLite in the default template) and do not replay on MySQL. They must be regenerated against MySQL before migrating."]},{category:"database",name:"singlestore",status:"experimental",implementation:"storage/framework/core/database/src/drivers/mysql.ts",testEvidence:[],topology:"client-server",prerequisites:["SingleStore service"],limitations:["MySQL wire compatibility exists, but a dedicated conformance matrix is not published."]},{category:"database",name:"vitess",status:"experimental",implementation:"storage/framework/core/database/src/drivers/mysql.ts",testEvidence:["storage/framework/core/database/tests/vitess-constraints.test.ts"],topology:"mysql-behind-vtgate",prerequisites:["A Vitess cluster reachable at vtgate"],limitations:["No live cluster in CI; the retained evidence covers unsharded and sharded DDL profiles plus VSchema generation, not a round trip through vtgate.","Set DB_VITESS_SHARDED=true for a sharded keyspace; those keyspaces reject cross-shard foreign keys and AUTO_INCREMENT, so use application-generated IDs and a VSchema.","Schema changes on sharded keyspaces should go through Vitess online DDL.","A transaction spanning shards is best-effort or two-phase, not the single-node ACID the ORM assumes."]},{category:"database",name:"postgres",status:"partial",implementation:"storage/framework/core/database/src/drivers/postgres.ts",testEvidence:["storage/framework/core/database/tests/postgres-pivot-timestamptz.test.ts"],topology:"client-server",prerequisites:["PostgreSQL service"],limitations:["The default CI suite does not provision PostgreSQL.","The migration files shipped under database/migrations are emitted for a single dialect (SQLite in the default template) and do not replay on PostgreSQL. They must be regenerated against PostgreSQL before migrating."]},{category:"database",name:"dynamodb",status:"unsupported",implementation:"storage/framework/core/database/src/drivers/dynamodb.ts",testEvidence:[],topology:"managed-service",prerequisites:["DynamoDB"],limitations:["DynamoDB helpers are not an ORM SQL driver and cannot be selected as database.default."]},{category:"queue",name:"sync",status:"supported",implementation:"storage/framework/core/queue/src/job.ts",testEvidence:["storage/framework/core/queue/tests/jobs.test.ts"],topology:"inline",prerequisites:[],limitations:["Not durable."]},{category:"queue",name:"database",status:"supported",implementation:"storage/framework/core/queue/src/job.ts",testEvidence:["storage/framework/core/queue/tests/integration.test.ts","storage/framework/core/queue/tests/failure-path-correctness.test.ts"],topology:"worker-and-embedded-sqlite",prerequisites:["Bun SQLite for the retained CI contract"],limitations:["Other SQL providers require their own provider evidence."]},{category:"queue",name:"redis",status:"supported",implementation:"storage/framework/core/queue/src/drivers/redis.ts",testEvidence:["storage/framework/core/queue/tests/redis-contract.test.ts"],topology:"worker-and-redis",prerequisites:["Redis 8.8 service"],limitations:["The retained contract covers queue persistence operations; horizontal scaling and distributed-lock extensions require separate evidence."],liveServiceContract:{service:"redis",version:"8.8.0",workflow:".github/workflows/ci.yml"}},{category:"queue",name:"sqs",status:"unsupported",implementation:null,testEvidence:[],topology:"managed-service",prerequisites:["AWS SQS"],limitations:["Configuration shape is reserved; dispatch fails loudly."]},{category:"queue",name:"memory",status:"unsupported",implementation:null,testEvidence:[],topology:"in-process",prerequisites:[],limitations:["Reserved driver name; dispatch fails loudly."]},{category:"queue",name:"beanstalkd",status:"unsupported",implementation:null,testEvidence:[],topology:"client-server",prerequisites:["Beanstalkd service"],limitations:["Reserved driver name; dispatch fails loudly."]},{category:"cache",name:"memory",status:"supported",implementation:"storage/framework/core/cache/src/drivers/index.ts",testEvidence:["storage/framework/core/cache/tests/Memory.test.ts","storage/framework/core/cache/tests/ttl.test.ts"],topology:"in-process",prerequisites:[],limitations:["Not shared across processes."]},{category:"cache",name:"redis",status:"supported",implementation:"storage/framework/core/cache/src/drivers/index.ts",testEvidence:["storage/framework/core/cache/tests/redis-contract.test.ts"],topology:"client-server",prerequisites:["Redis 8.8 service"],limitations:["The retained contract covers core cache and TTL operations; TLS/authenticated deployments require separate provider evidence."],liveServiceContract:{service:"redis",version:"8.8.0",workflow:".github/workflows/ci.yml"}},{category:"cache",name:"singlestore",status:"experimental",implementation:"storage/framework/core/cache/src/drivers/singlestore.ts",testEvidence:[],topology:"client-server",prerequisites:["SingleStore service"],limitations:["No dedicated CI service matrix."]},{category:"storage",name:"local",status:"supported",implementation:"storage/framework/core/storage/src/adapters/local.ts",testEvidence:["storage/framework/core/storage/tests/localStorage.test.ts","storage/framework/core/storage/tests/deep-integration.test.ts"],topology:"local-filesystem",prerequisites:[],limitations:[]},{category:"storage",name:"memory",status:"supported",implementation:"storage/framework/core/storage/src/adapters/memory.ts",testEvidence:["storage/framework/core/storage/tests/memoryAdapter.test.ts"],topology:"in-process",prerequisites:[],limitations:["Not persistent."]},{category:"storage",name:"s3",status:"partial",implementation:"storage/framework/core/storage/src/adapters/s3.ts",testEvidence:["storage/framework/core/storage/tests/s3-presigned-post.test.ts"],topology:"managed-object-storage",prerequisites:["S3-compatible service and credentials"],limitations:["CI covers request construction but not a live provider round trip."]},{category:"storage",name:"bun",status:"partial",implementation:"storage/framework/core/storage/src/adapters/bun.ts",testEvidence:["storage/framework/core/storage/tests/bunAdapter.test.ts"],topology:"local-filesystem",prerequisites:["Bun runtime"],limitations:["Adapter-specific feature parity is not fully reported."]},{category:"storage",name:"azure",status:"partial",implementation:"storage/framework/core/storage/src/adapters/azure.ts",testEvidence:["storage/framework/core/storage/tests/azure-adapter.test.ts","storage/framework/core/storage/tests/azure-signing.test.ts"],topology:"managed-object-storage",prerequisites:["An Azure storage account, a container, and an account key or SAS token"],limitations:["CI covers Shared Key and service-SAS signing plus request construction, not a live container round trip.","Visibility is a container property on Azure, so changeVisibility() refuses rather than silently doing nothing; a per-object grant is signedUrl().","ensureConfiguredBuckets provisions S3 buckets only, so the container must exist before the disk is used."]},{category:"mail",name:"log",status:"supported",implementation:"storage/framework/core/email/src/drivers/log.ts",testEvidence:["storage/framework/core/email/tests/email.test.ts"],topology:"local-file",prerequisites:[],limitations:["Development/testing transport only."]},{category:"mail",name:"capture",status:"supported",implementation:"storage/framework/core/email/src/drivers/capture.ts",testEvidence:["storage/framework/core/email/tests/email.test.ts"],topology:"in-process",prerequisites:[],limitations:["Testing transport only."]},...["smtp","ses","sendgrid","mailgun","mailtrap"].map((name)=>({category:"mail",name,status:"partial",implementation:`storage/framework/core/email/src/drivers/${name}.ts`,testEvidence:["storage/framework/core/email/tests/driver-credentials.test.ts"],topology:name==="smtp"?"smtp-server":"managed-service",prerequisites:[`${name} credentials`],limitations:["CI validates configuration and request behavior without a live delivery assertion."]})),{category:"realtime",name:"websocket",status:"supported",implementation:"storage/framework/core/realtime/src/ws.ts",testEvidence:["storage/framework/core/realtime/tests/ws-auth.test.ts","storage/framework/core/realtime/tests/backpressure.test.ts"],topology:"single-process-websocket",prerequisites:["Bun server"],limitations:["Scale-out requires an application-provided fan-out layer."]},{category:"deploy",name:"ts-cloud-hetzner",status:"experimental",implementation:"storage/framework/core/buddy/src/commands/deploy.ts",testEvidence:["storage/framework/core/buddy/tests/deploy-ssh-target.test.ts"],topology:"hetzner-vm-systemd-rpx",prerequisites:["@stacksjs/ts-cloud","Hetzner credentials","SSH key"],limitations:["Live provider evidence and rollback conformance are not yet retained in the protocol report."]},{category:"deploy",name:"ts-cloud-ssh",status:"experimental",implementation:"storage/framework/core/buddy/src/commands/deploy-ssh-target.ts",testEvidence:["storage/framework/core/buddy/tests/deploy-ssh-target.test.ts"],topology:"ssh-box-systemd-rpx",prerequisites:["@stacksjs/ts-cloud with the ssh driver","A 64-bit Debian or Ubuntu host reachable over SSH","Passwordless sudo when deploying as a non-root user"],limitations:["DNS, TLS issuance, CDN and mail reconciliation are skipped for a host on a private address.","One app host per project; multi-host ssh fleets are not supported.","No live hardware evidence is retained in CI."]}];export function capabilityDrivers(category){return capabilityRegistry.filter((driver)=>driver.category===category)}export function findCapability(category,name){return capabilityRegistry.find((driver)=>driver.category===category&&driver.name===name)}export function assertCapabilityAvailable(category,name){const capability=findCapability(category,name);if(!capability){const known=capabilityDrivers(category).map((driver)=>driver.name).join(", ");throw Error(`[config] Unknown ${category} driver "${name}". Known drivers: ${known}`)}if(capability.status==="unsupported")throw Error(`[config] ${category} driver "${name}" is unsupported: ${capability.limitations.join(" ")}`);return capability}
+export const REMOTE_TOPOLOGIES=new Set(["client-server","managed-service","managed-object-storage","mysql-behind-vtgate","smtp-server","worker-and-redis","hetzner-vm-systemd-rpx","ssh-box-systemd-rpx"]);export function isRemoteTopology(topology){return REMOTE_TOPOLOGIES.has(topology)}export const capabilityRegistry=[{category:"database",name:"sqlite",status:"supported",implementation:"storage/framework/core/database/src/drivers/sqlite.ts",testEvidence:["storage/framework/core/database/tests/integration.test.ts","storage/framework/core/database/tests/sqlite-tx-serialization.test.ts"],topology:"embedded",prerequisites:["Bun SQLite"],limitations:[]},{category:"database",name:"mysql",status:"partial",implementation:"storage/framework/core/database/src/drivers/mysql.ts",testEvidence:["storage/framework/core/database/tests/integration.test.ts"],topology:"client-server",prerequisites:["MySQL service"],limitations:["The default CI suite does not yet publish a dedicated dialect report.","The migration files shipped under database/migrations are emitted for a single dialect (SQLite in the default template) and do not replay on MySQL. They must be regenerated against MySQL before migrating."]},{category:"database",name:"singlestore",status:"experimental",implementation:"storage/framework/core/database/src/drivers/mysql.ts",testEvidence:[],topology:"client-server",prerequisites:["SingleStore service"],limitations:["MySQL wire compatibility exists, but a dedicated conformance matrix is not published."]},{category:"database",name:"vitess",status:"experimental",implementation:"storage/framework/core/database/src/drivers/mysql.ts",testEvidence:["storage/framework/core/database/tests/vitess-constraints.test.ts"],topology:"mysql-behind-vtgate",prerequisites:["A Vitess cluster reachable at vtgate"],limitations:["No live cluster in CI; the retained evidence covers unsharded and sharded DDL profiles plus VSchema generation, not a round trip through vtgate.","Set DB_VITESS_SHARDED=true for a sharded keyspace; those keyspaces reject cross-shard foreign keys and AUTO_INCREMENT, so use application-generated IDs and a VSchema.","Schema changes on sharded keyspaces should go through Vitess online DDL.","A transaction spanning shards is best-effort or two-phase, not the single-node ACID the ORM assumes."]},{category:"database",name:"postgres",status:"partial",implementation:"storage/framework/core/database/src/drivers/postgres.ts",testEvidence:["storage/framework/core/database/tests/postgres-pivot-timestamptz.test.ts"],topology:"client-server",prerequisites:["PostgreSQL service"],limitations:["The default CI suite does not provision PostgreSQL.","The migration files shipped under database/migrations are emitted for a single dialect (SQLite in the default template) and do not replay on PostgreSQL. They must be regenerated against PostgreSQL before migrating."]},{category:"database",name:"dynamodb",status:"unsupported",implementation:"storage/framework/core/database/src/drivers/dynamodb.ts",testEvidence:[],topology:"managed-service",prerequisites:["DynamoDB"],limitations:["DynamoDB helpers are not an ORM SQL driver and cannot be selected as database.default."]},{category:"queue",name:"sync",status:"supported",implementation:"storage/framework/core/queue/src/job.ts",testEvidence:["storage/framework/core/queue/tests/jobs.test.ts"],topology:"inline",prerequisites:[],limitations:["Not durable."]},{category:"queue",name:"database",status:"supported",implementation:"storage/framework/core/queue/src/job.ts",testEvidence:["storage/framework/core/queue/tests/integration.test.ts","storage/framework/core/queue/tests/failure-path-correctness.test.ts"],topology:"worker-and-embedded-sqlite",prerequisites:["Bun SQLite for the retained CI contract"],limitations:["Other SQL providers require their own provider evidence."]},{category:"queue",name:"redis",status:"supported",implementation:"storage/framework/core/queue/src/drivers/redis.ts",testEvidence:["storage/framework/core/queue/tests/redis-contract.test.ts"],topology:"worker-and-redis",prerequisites:["Redis 8.8 service"],limitations:["The retained contract covers queue persistence operations; horizontal scaling and distributed-lock extensions require separate evidence."],liveServiceContract:{service:"redis",version:"8.8.0",workflow:".github/workflows/ci.yml"}},{category:"queue",name:"sqs",status:"unsupported",implementation:null,testEvidence:[],topology:"managed-service",prerequisites:["AWS SQS"],limitations:["Configuration shape is reserved; dispatch fails loudly."]},{category:"queue",name:"memory",status:"unsupported",implementation:null,testEvidence:[],topology:"in-process",prerequisites:[],limitations:["Reserved driver name; dispatch fails loudly."]},{category:"queue",name:"beanstalkd",status:"unsupported",implementation:null,testEvidence:[],topology:"client-server",prerequisites:["Beanstalkd service"],limitations:["Reserved driver name; dispatch fails loudly."]},{category:"cache",name:"memory",status:"supported",implementation:"storage/framework/core/cache/src/drivers/index.ts",testEvidence:["storage/framework/core/cache/tests/Memory.test.ts","storage/framework/core/cache/tests/ttl.test.ts"],topology:"in-process",prerequisites:[],limitations:["Not shared across processes."]},{category:"cache",name:"redis",status:"supported",implementation:"storage/framework/core/cache/src/drivers/index.ts",testEvidence:["storage/framework/core/cache/tests/redis-contract.test.ts"],topology:"client-server",prerequisites:["Redis 8.8 service"],limitations:["The retained contract covers core cache and TTL operations; TLS/authenticated deployments require separate provider evidence."],liveServiceContract:{service:"redis",version:"8.8.0",workflow:".github/workflows/ci.yml"}},{category:"cache",name:"singlestore",status:"experimental",implementation:"storage/framework/core/cache/src/drivers/singlestore.ts",testEvidence:[],topology:"client-server",prerequisites:["SingleStore service"],limitations:["No dedicated CI service matrix."]},{category:"storage",name:"local",status:"supported",implementation:"storage/framework/core/storage/src/adapters/local.ts",testEvidence:["storage/framework/core/storage/tests/localStorage.test.ts","storage/framework/core/storage/tests/deep-integration.test.ts"],topology:"local-filesystem",prerequisites:[],limitations:[]},{category:"storage",name:"memory",status:"supported",implementation:"storage/framework/core/storage/src/adapters/memory.ts",testEvidence:["storage/framework/core/storage/tests/memoryAdapter.test.ts"],topology:"in-process",prerequisites:[],limitations:["Not persistent."]},{category:"storage",name:"s3",status:"partial",implementation:"storage/framework/core/storage/src/adapters/s3.ts",testEvidence:["storage/framework/core/storage/tests/s3-presigned-post.test.ts"],topology:"managed-object-storage",prerequisites:["S3-compatible service and credentials"],limitations:["CI covers request construction but not a live provider round trip."]},{category:"storage",name:"bun",status:"partial",implementation:"storage/framework/core/storage/src/adapters/bun.ts",testEvidence:["storage/framework/core/storage/tests/bunAdapter.test.ts"],topology:"local-filesystem",prerequisites:["Bun runtime"],limitations:["Adapter-specific feature parity is not fully reported."]},{category:"storage",name:"azure",status:"partial",implementation:"storage/framework/core/storage/src/adapters/azure.ts",testEvidence:["storage/framework/core/storage/tests/azure-adapter.test.ts","storage/framework/core/storage/tests/azure-signing.test.ts"],topology:"managed-object-storage",prerequisites:["An Azure storage account, a container, and an account key or SAS token"],limitations:["CI covers Shared Key and service-SAS signing plus request construction, not a live container round trip.","Visibility is a container property on Azure, so changeVisibility() refuses rather than silently doing nothing; a per-object grant is signedUrl().","ensureConfiguredBuckets provisions S3 buckets only, so the container must exist before the disk is used."]},{category:"mail",name:"log",status:"supported",implementation:"storage/framework/core/email/src/drivers/log.ts",testEvidence:["storage/framework/core/email/tests/email.test.ts"],topology:"local-file",prerequisites:[],limitations:["Development/testing transport only."]},{category:"mail",name:"capture",status:"supported",implementation:"storage/framework/core/email/src/drivers/capture.ts",testEvidence:["storage/framework/core/email/tests/email.test.ts"],topology:"in-process",prerequisites:[],limitations:["Testing transport only."]},...["smtp","ses","sendgrid","mailgun","mailtrap"].map((name)=>({category:"mail",name,status:"partial",implementation:`storage/framework/core/email/src/drivers/${name}.ts`,testEvidence:["storage/framework/core/email/tests/driver-credentials.test.ts"],topology:name==="smtp"?"smtp-server":"managed-service",prerequisites:[`${name} credentials`],limitations:["CI validates configuration and request behavior without a live delivery assertion."]})),{category:"realtime",name:"websocket",status:"supported",implementation:"storage/framework/core/realtime/src/ws.ts",testEvidence:["storage/framework/core/realtime/tests/ws-auth.test.ts","storage/framework/core/realtime/tests/backpressure.test.ts"],topology:"single-process-websocket",prerequisites:["Bun server"],limitations:["Scale-out requires an application-provided fan-out layer."]},{category:"deploy",name:"ts-cloud-hetzner",status:"experimental",implementation:"storage/framework/core/buddy/src/commands/deploy.ts",testEvidence:["storage/framework/core/buddy/tests/deploy-ssh-target.test.ts"],topology:"hetzner-vm-systemd-rpx",prerequisites:["@stacksjs/ts-cloud","Hetzner credentials","SSH key"],limitations:["Live provider evidence and rollback conformance are not yet retained in the protocol report."]},{category:"deploy",name:"ts-cloud-ssh",status:"experimental",implementation:"storage/framework/core/buddy/src/commands/deploy-ssh-target.ts",testEvidence:["storage/framework/core/buddy/tests/deploy-ssh-target.test.ts"],topology:"ssh-box-systemd-rpx",prerequisites:["@stacksjs/ts-cloud with the ssh driver","A 64-bit Debian or Ubuntu host reachable over SSH","Passwordless sudo when deploying as a non-root user"],limitations:["DNS, TLS issuance, CDN and mail reconciliation are skipped for a host on a private address.","One app host per project; multi-host ssh fleets are not supported.","No live hardware evidence is retained in CI."]}];export function capabilityDrivers(category){return capabilityRegistry.filter((driver)=>driver.category===category)}export function findCapability(category,name){return capabilityRegistry.find((driver)=>driver.category===category&&driver.name===name)}export function assertCapabilityAvailable(category,name){const capability=findCapability(category,name);if(!capability){const known=capabilityDrivers(category).map((driver)=>driver.name).join(", ");throw Error(`[config] Unknown ${category} driver "${name}". Known drivers: ${known}`)}if(capability.status==="unsupported")throw Error(`[config] ${category} driver "${name}" is unsupported: ${capability.limitations.join(" ")}`);return capability}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/config",
   "type": "module",
   "sideEffects": false,
-  "version": "0.74.37",
+  "version": "0.74.39",
   "description": "The Stacks config helper methods.",
   "author": "Chris Breuer",
   "contributors": [
@@ -55,14 +55,14 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/events": "0.74.37",
-    "@stacksjs/path": "0.74.37",
-    "@stacksjs/tunnel": "0.74.37",
+    "@stacksjs/events": "0.74.39",
+    "@stacksjs/path": "0.74.39",
+    "@stacksjs/tunnel": "0.74.39",
     "ts-pantry": "^0.11.35"
   },
   "devDependencies": {
-    "@stacksjs/alias": "0.74.37",
-    "@stacksjs/types": "0.74.37",
+    "@stacksjs/alias": "0.74.39",
+    "@stacksjs/types": "0.74.39",
     "better-dx": "^0.2.24"
   }
 }