@everystack/cli 0.2.39 → 0.2.40

package/README.md

@@ -103,6 +103,33 @@ const storage = createStorage({
 });
 ```
 
+The S3 client is **bounded by default** so a single call can never hang: a
+connect timeout (3s), a per-request timeout (10s), bounded retries (3 attempts),
+and a capped `list()` (paged with a page backstop). This matters most for the
+observability rollup — an unbounded client under an S3 503 storm blocks until
+the Lambda's own timeout, and each hung invocation pins a concurrency slot, so
+it can drain the account pool and starve the app it observes.
+
+Tune per-field via `options`, or override the timeouts/retries by env var
+without a code change (env is handy for turning a knob on a live Lambda):
+
+```typescript
+const storage = createStorage({
+  type: 's3',
+  bucket: 'my-updates-bucket',
+  region: 'us-east-1',
+  options: {
+    connectionTimeoutMs: 3000, // env: EVERYSTACK_S3_CONNECT_TIMEOUT_MS
+    requestTimeoutMs: 10000,    // env: EVERYSTACK_S3_REQUEST_TIMEOUT_MS
+    maxAttempts: 3,             // env: EVERYSTACK_S3_MAX_ATTEMPTS
+    listMaxKeys: 1000,          // keys per ListObjectsV2 page
+    listMaxPages: 1000,         // hard backstop before list() truncates (warns)
+  },
+});
+```
+
+Precedence per field: explicit `options` > env var > default.
+
 ### Custom Adapter
 
 Implement the `StorageAdapter` interface:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.2.39",
+  "version": "0.2.40",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -53,6 +53,12 @@
   "bin": {
     "everystack": "./src/cli/index.ts"
   },
+  "scripts": {
+    "test": "jest",
+    "build": "tsc --build",
+    "prepublishOnly": "tsc --module commonjs --moduleResolution node --target ES2022 --esModuleInterop --skipLibCheck --declaration false --outDir src src/env.ts",
+    "lint": "tsc --noEmit"
+  },
   "dependencies": {
     "@aws-sdk/client-cloudfront": "3.1053.0",
     "@aws-sdk/client-cloudfront-keyvaluestore": "3.1053.0",
@@ -123,10 +129,5 @@
     "react": "19.2.6",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3"
-  },
-  "scripts": {
-    "test": "jest",
-    "build": "tsc --build",
-    "lint": "tsc --noEmit"
   }
-}
+}

package/src/cli/authz-contract-io.ts

@@ -0,0 +1,92 @@
+/**
+ * Filesystem IO for the Authorization Contract — write/load the per-table files.
+ *
+ * Kept out of authz-contract.ts so the core (introspect/assemble/diff) stays pure and
+ * fs-free. The serialized form is deterministic and byte-stable: a re-pull of an
+ * unchanged database produces identical files, so a contract change is always a real,
+ * reviewable git diff and never reformatting noise.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { AuthzContract, TableContract, FunctionContract } from './authz-contract.js';
+import { renderContractMarkdown } from './authz-render.js';
+
+/** The human-readable review doc written alongside the JSON. */
+export const REVIEW_FILE = 'AUTHORIZATION.md';
+
+/** Stable JSON: object keys sorted recursively, 2-space indent, trailing newline. */
+export function stableStringify(value: unknown): string {
+  const sortKeys = (v: any): any => {
+    if (Array.isArray(v)) return v.map(sortKeys);
+    if (v && typeof v === 'object') {
+      return Object.fromEntries(Object.keys(v).sort().map((k) => [k, sortKeys(v[k])]));
+    }
+    return v;
+  };
+  return JSON.stringify(sortKeys(value), null, 2) + '\n';
+}
+
+/** `public.posts` -> `public.posts.contract.json`. */
+export function tableFileName(table: string): string {
+  return `${table}.contract.json`;
+}
+
+export const FUNCTIONS_FILE = '_functions.contract.json';
+
+/**
+ * Write the contract as one file per table plus `_functions.contract.json`. Prunes any
+ * stale `*.contract.json` for a table no longer in the contract, so a dropped table
+ * leaves no orphan file. The directory is created if absent.
+ */
+export async function writeContract(dir: string, contract: AuthzContract): Promise<string[]> {
+  await fs.mkdir(dir, { recursive: true });
+
+  const written = new Set<string>();
+  for (const table of contract.tables) {
+    const file = tableFileName(table.table);
+    await fs.writeFile(path.join(dir, file), stableStringify(table), 'utf8');
+    written.add(file);
+  }
+  await fs.writeFile(path.join(dir, FUNCTIONS_FILE), stableStringify({ functions: contract.functions }), 'utf8');
+  written.add(FUNCTIONS_FILE);
+
+  for (const existing of await listContractFiles(dir)) {
+    if (!written.has(existing)) await fs.rm(path.join(dir, existing));
+  }
+
+  // The human-readable review doc, regenerated from the same contract so it can't drift.
+  await fs.writeFile(path.join(dir, REVIEW_FILE), renderContractMarkdown(contract), 'utf8');
+  written.add(REVIEW_FILE);
+  return [...written].sort();
+}
+
+/** Load the per-table files back into a contract. Missing dir -> empty contract. */
+export async function loadContract(dir: string): Promise<AuthzContract> {
+  let files: string[];
+  try {
+    files = await listContractFiles(dir);
+  } catch {
+    return { tables: [], functions: [] };
+  }
+
+  const tables: TableContract[] = [];
+  let functions: FunctionContract[] = [];
+  for (const file of files) {
+    const raw = await fs.readFile(path.join(dir, file), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (file === FUNCTIONS_FILE) {
+      functions = parsed.functions ?? [];
+    } else {
+      tables.push(parsed as TableContract);
+    }
+  }
+  tables.sort((a, b) => a.table.localeCompare(b.table));
+  functions.sort((a, b) => a.name.localeCompare(b.name));
+  return { tables, functions };
+}
+
+async function listContractFiles(dir: string): Promise<string[]> {
+  const entries = await fs.readdir(dir);
+  return entries.filter((f) => f.endsWith('.contract.json'));
+}