sandstream-kit 1.0.0

package/dist/cost-monitor.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Cost monitoring for the spend-cap policy declared in
+ * `.kit-allowlist.json` (see security-policy.ts).
+ *
+ * v1 scope: provider adapters that have a stable public usage / balance API
+ * accessible via the same key already in the env. Anything that requires
+ * paid analytics endpoints (Stripe Sigma) or a billing-dashboard scrape is
+ * out of scope — we don't want kit to need a separate API.
+ *
+ * Concretely supported today:
+ *   - Stripe: `GET /v1/balance` (live + pending balance, all currencies)
+ *
+ * Stubbed (returns "not implemented" until a public API exists):
+ *   - OpenAI / Anthropic — usage endpoints require dashboard scraping
+ *   - Resend — no usage API
+ *   - Vercel — usage endpoint exists but rate-limited per-account
+ */
+export interface CostSample {
+    provider: string;
+    /** Logical key the policy is attached to (e.g. STRIPE_SECRET_KEY) */
+    policyKey: string;
+    /** Current usage / balance figure */
+    current: number;
+    unit: "usd" | "eur" | "sek" | "tokens" | "requests";
+    /** Spend cap from policy, if declared */
+    capUsd?: number;
+    /** Plain-text status string suitable for table display */
+    status: "ok" | "warn" | "over-cap" | "no-cap" | "no-api" | "auth-failed" | "skipped";
+    detail: string;
+}
+export declare function sampleCosts(opts: {
+    /** Per-key spend cap from policy, keyed by env-var name. */
+    caps: Record<string, number | undefined>;
+    /** Allow injection (used in tests) instead of reading process.env. */
+    env?: Record<string, string | undefined>;
+}): Promise<CostSample[]>;
+export interface CostBaseline {
+    /** Provider key (e.g. STRIPE_SECRET_KEY). */
+    policyKey: string;
+    /** Average daily spend over the last N samples. */
+    avgDailyUsd: number;
+    /** Most recent observation. */
+    lastSampleUsd: number;
+    /** When last updated (ISO). */
+    updatedAt: string;
+    /** Number of samples contributing to avgDailyUsd. */
+    sampleCount: number;
+}
+export interface AnomalyAlert {
+    policyKey: string;
+    provider: string;
+    currentUsd: number;
+    baselineUsd: number;
+    multiplier: number;
+    severity: "info" | "warn" | "critical";
+    detail: string;
+}
+/**
+ * Compare new samples against stored baselines. Returns alerts for any
+ * provider whose current reading exceeds the baseline by a configurable
+ * multiplier. Updates baselines in place so subsequent calls see the new
+ * average.
+ *
+ *   warn  ≥ 2× baseline
+ *   critical ≥ 4× baseline OR > 1.5× capUsd if a cap is declared
+ */
+export declare function detectCostAnomalies(samples: CostSample[], opts?: {
+    cwd?: string;
+    warnMultiplier?: number;
+    criticalMultiplier?: number;
+    persist?: boolean;
+}): Promise<AnomalyAlert[]>;

package/dist/cost-monitor.js

@@ -0,0 +1,218 @@
+/**
+ * Cost monitoring for the spend-cap policy declared in
+ * `.kit-allowlist.json` (see security-policy.ts).
+ *
+ * v1 scope: provider adapters that have a stable public usage / balance API
+ * accessible via the same key already in the env. Anything that requires
+ * paid analytics endpoints (Stripe Sigma) or a billing-dashboard scrape is
+ * out of scope — we don't want kit to need a separate API.
+ *
+ * Concretely supported today:
+ *   - Stripe: `GET /v1/balance` (live + pending balance, all currencies)
+ *
+ * Stubbed (returns "not implemented" until a public API exists):
+ *   - OpenAI / Anthropic — usage endpoints require dashboard scraping
+ *   - Resend — no usage API
+ *   - Vercel — usage endpoint exists but rate-limited per-account
+ */
+async function stripeAdapter(key, opts) {
+    // `https://api.stripe.com/v1/balance` returns `{ available: [{amount, currency}], pending: [...] }`.
+    // Amounts are in the currency's smallest unit (cents). We sum availability
+    // across currencies and surface it as the dominant currency for clarity.
+    try {
+        const res = await fetch("https://api.stripe.com/v1/balance", {
+            headers: { Authorization: `Bearer ${key}` },
+            signal: AbortSignal.timeout(8000),
+        });
+        if (res.status === 401) {
+            return {
+                provider: "stripe",
+                policyKey: "STRIPE_SECRET_KEY",
+                current: 0,
+                unit: "usd",
+                capUsd: opts.capUsd,
+                status: "auth-failed",
+                detail: "Stripe key not authorized (rotate / re-check restricted scopes)",
+            };
+        }
+        if (!res.ok) {
+            return {
+                provider: "stripe",
+                policyKey: "STRIPE_SECRET_KEY",
+                current: 0,
+                unit: "usd",
+                capUsd: opts.capUsd,
+                status: "no-api",
+                detail: `Stripe /v1/balance returned ${res.status}`,
+            };
+        }
+        const data = (await res.json());
+        const sumCents = [...data.available, ...data.pending].reduce((sum, b) => sum + b.amount, 0);
+        const usd = sumCents / 100;
+        const cap = opts.capUsd;
+        const status = cap === undefined
+            ? "no-cap"
+            : usd > cap
+                ? "over-cap"
+                : usd > cap * 0.8
+                    ? "warn"
+                    : "ok";
+        return {
+            provider: "stripe",
+            policyKey: "STRIPE_SECRET_KEY",
+            current: usd,
+            unit: "usd",
+            capUsd: cap,
+            status,
+            detail: `available + pending across all currencies, converted at 1:1 (kit doesn't FX)`,
+        };
+    }
+    catch (err) {
+        return {
+            provider: "stripe",
+            policyKey: "STRIPE_SECRET_KEY",
+            current: 0,
+            unit: "usd",
+            capUsd: opts.capUsd,
+            status: "no-api",
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+const STUB_PROVIDERS = {
+    OPENAI_API_KEY: {
+        envKey: "OPENAI_API_KEY",
+        reason: "OpenAI usage endpoint requires dashboard auth; no key-bearable API yet",
+    },
+    ANTHROPIC_API_KEY: {
+        envKey: "ANTHROPIC_API_KEY",
+        reason: "Anthropic billing API is dashboard-only",
+    },
+    RESEND_API_KEY: {
+        envKey: "RESEND_API_KEY",
+        reason: "Resend exposes send-counts in the dashboard, not via key auth",
+    },
+    VERCEL_API_TOKEN: {
+        envKey: "VERCEL_API_TOKEN",
+        reason: "Vercel usage endpoint requires team-id + rate-limited",
+    },
+};
+const ADAPTERS = {
+    STRIPE_SECRET_KEY: stripeAdapter,
+};
+export async function sampleCosts(opts) {
+    const env = opts.env ?? process.env;
+    const samples = [];
+    for (const [keyName, adapter] of Object.entries(ADAPTERS)) {
+        const value = env[keyName];
+        if (!value)
+            continue;
+        samples.push(await adapter(value, { capUsd: opts.caps[keyName] }));
+    }
+    for (const [keyName, info] of Object.entries(STUB_PROVIDERS)) {
+        const value = env[info.envKey];
+        if (!value)
+            continue;
+        samples.push({
+            provider: keyName.replace("_API_KEY", "").toLowerCase(),
+            policyKey: keyName,
+            current: 0,
+            unit: "usd",
+            capUsd: opts.caps[keyName],
+            status: "no-api",
+            detail: info.reason,
+        });
+    }
+    return samples;
+}
+// ── Anomaly detection (P3.1 leak-detection layer) ──────────────────────────
+//
+// kit's existing cost-monitor surfaces CURRENT balance. For leak detection
+// we need a BASELINE and a sliding window: a key that suddenly burns 3× its
+// usual spend is the signal that matters. Baseline is stored locally
+// (.kit-cost-baseline.json) and refreshed on a rolling window.
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+const BASELINE_FILE = ".kit-cost-baseline.json";
+async function loadBaselines(cwd) {
+    try {
+        const raw = await readFile(resolve(cwd, BASELINE_FILE), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+async function saveBaselines(cwd, baselines) {
+    await writeFile(resolve(cwd, BASELINE_FILE), JSON.stringify(baselines, null, 2) + "\n", "utf-8");
+}
+/**
+ * Update the rolling baseline for a sample. Simple exponential-moving-average
+ * with weight 0.2 on the new sample so a single spike doesn't anchor the
+ * baseline; instead, sustained-high readings raise the floor over time.
+ */
+function updateBaseline(prev, sample) {
+    const weight = 0.2;
+    const prevAvg = prev?.avgDailyUsd ?? sample.current;
+    const newAvg = prev ? prevAvg * (1 - weight) + sample.current * weight : sample.current;
+    return {
+        policyKey: sample.policyKey,
+        avgDailyUsd: newAvg,
+        lastSampleUsd: sample.current,
+        updatedAt: new Date().toISOString(),
+        sampleCount: (prev?.sampleCount ?? 0) + 1,
+    };
+}
+/**
+ * Compare new samples against stored baselines. Returns alerts for any
+ * provider whose current reading exceeds the baseline by a configurable
+ * multiplier. Updates baselines in place so subsequent calls see the new
+ * average.
+ *
+ *   warn  ≥ 2× baseline
+ *   critical ≥ 4× baseline OR > 1.5× capUsd if a cap is declared
+ */
+export async function detectCostAnomalies(samples, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const warnX = opts.warnMultiplier ?? 2;
+    const critX = opts.criticalMultiplier ?? 4;
+    const persist = opts.persist ?? true;
+    const baselines = await loadBaselines(cwd);
+    const alerts = [];
+    for (const sample of samples) {
+        if (sample.status === "auth-failed" || sample.status === "no-api")
+            continue;
+        const prev = baselines[sample.policyKey];
+        const baseline = prev?.avgDailyUsd ?? sample.current;
+        const multiplier = baseline > 0 ? sample.current / baseline : 1;
+        let severity = null;
+        if (sample.capUsd && sample.current > sample.capUsd * 1.5) {
+            severity = "critical";
+        }
+        else if (multiplier >= critX) {
+            severity = "critical";
+        }
+        else if (multiplier >= warnX) {
+            severity = "warn";
+        }
+        if (severity) {
+            alerts.push({
+                policyKey: sample.policyKey,
+                provider: sample.provider,
+                currentUsd: sample.current,
+                baselineUsd: baseline,
+                multiplier,
+                severity,
+                detail: sample.capUsd
+                    ? `current ${sample.current.toFixed(2)} USD vs baseline ${baseline.toFixed(2)} (${multiplier.toFixed(1)}×); cap ${sample.capUsd}`
+                    : `current ${sample.current.toFixed(2)} USD vs baseline ${baseline.toFixed(2)} (${multiplier.toFixed(1)}×)`,
+            });
+        }
+        baselines[sample.policyKey] = updateBaseline(prev, sample);
+    }
+    if (persist) {
+        await saveBaselines(cwd, baselines);
+    }
+    return alerts;
+}
+//# sourceMappingURL=cost-monitor.js.map

package/dist/cost-monitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-monitor.js","sourceRoot":"","sources":["../src/cost-monitor.ts"],"names":[],"mappings":"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"}

package/dist/create-plugin.d.ts

@@ -0,0 +1,22 @@
+export interface CreatePluginOptions {
+    /** Plugin short name, e.g. "aws-s3" → package "sandstream-kit-plugin-aws-s3" */
+    name: string;
+    /** Directory to create the plugin in (defaults to cwd) */
+    cwd?: string;
+    /** Skip running npm install after scaffolding */
+    skipInstall?: boolean;
+}
+export interface CreatePluginResult {
+    success: boolean;
+    pluginDir: string;
+    packageName: string;
+    message: string;
+    nextSteps: string[];
+}
+/**
+ * Scaffold a new kit adapter plugin from the reference template.
+ *
+ * Creates `./kit-plugin-<name>/` with a working TypeScript adapter
+ * that builds and passes tests immediately.
+ */
+export declare function createPlugin(opts: CreatePluginOptions): Promise<CreatePluginResult>;

package/dist/create-plugin.js

@@ -0,0 +1,266 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import { exec } from "./utils/exec.js";
+/**
+ * Scaffold a new kit adapter plugin from the reference template.
+ *
+ * Creates `./kit-plugin-<name>/` with a working TypeScript adapter
+ * that builds and passes tests immediately.
+ */
+export async function createPlugin(opts) {
+    const { name } = opts;
+    const cwd = opts.cwd ?? process.cwd();
+    // Normalise: strip "kit-plugin-" prefix if the user passed the full name.
+    // Community plugins use the unscoped `kit-plugin-<name>` convention (cf. eslint-plugin-*);
+    // only first-party packages live under the @sandstream scope.
+    const shortName = name.replace(/^kit-plugin-/, "");
+    const packageName = `kit-plugin-${shortName}`;
+    const pluginDir = resolve(cwd, packageName);
+    // Capitalise for class/export names: "aws-s3" → "AwsS3", "my-service" → "MyService"
+    const titleCase = shortName
+        .split(/[-_]/)
+        .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+        .join("");
+    const adapterName = `${titleCase.charAt(0).toLowerCase()}${titleCase.slice(1)}Adapter`;
+    const serviceName = shortName; // e.g. "aws-s3/deploy" — user can change
+    await mkdir(pluginDir, { recursive: true });
+    await mkdir(join(pluginDir, "src"), { recursive: true });
+    const typesDir = join(pluginDir, "src", "types");
+    await mkdir(typesDir, { recursive: true });
+    await writeFile(join(pluginDir, "package.json"), packageJsonTemplate(packageName), "utf-8");
+    await writeFile(join(pluginDir, "tsconfig.json"), tsconfigTemplate(), "utf-8");
+    await writeFile(join(pluginDir, "README.md"), readmeTemplate(packageName, shortName), "utf-8");
+    await writeFile(join(typesDir, "adapter-sdk.d.ts"), adapterSdkStub(), "utf-8");
+    await writeFile(join(pluginDir, "src", `${shortName}.ts`), adapterTemplate(adapterName, serviceName), "utf-8");
+    await writeFile(join(pluginDir, "src", `${shortName}.test.ts`), testTemplate(adapterName, serviceName), "utf-8");
+    await writeFile(join(pluginDir, "src", "index.ts"), indexTemplate(adapterName, shortName), "utf-8");
+    if (!opts.skipInstall) {
+        try {
+            await exec("npm", ["install"], { cwd: pluginDir, timeout: 60_000 });
+        }
+        catch {
+            // Non-fatal: user can run manually
+        }
+    }
+    return {
+        success: true,
+        pluginDir,
+        packageName,
+        message: `Created ${packageName} in ./${packageName}/`,
+        nextSteps: [
+            `cd ${packageName}`,
+            `npm run build`,
+            `npm test`,
+            `# Edit src/${shortName}.ts to implement your adapter`,
+            `# Then publish: npm publish`,
+            `# And add to your project: { "kitPlugins": ["${packageName}"] }`,
+        ],
+    };
+}
+// ─── templates ────────────────────────────────────────────────────────────────
+function adapterSdkStub() {
+    return `/**
+ * Bundled type stub for sandstream-kit-adapter-sdk.
+ * This file lets the plugin build standalone without installing the SDK package.
+ *
+ * When sandstream-kit-adapter-sdk is published to npm, you can:
+ * 1. Run: npm install --save-dev sandstream-kit-adapter-sdk
+ * 2. Remove the paths alias from tsconfig.json
+ * 3. Delete this file
+ */
+
+export interface ProvisionResult {
+  success: boolean;
+  message: string;
+  secrets?: Record<string, string>;
+  config?: Record<string, unknown>;
+  error?: string;
+}
+
+export interface AdapterContext {
+  projectName?: string;
+  projectPath: string;
+  existingEnv: Record<string, string>;
+}
+
+export interface ServiceAdapter {
+  name: string;
+  description: string;
+  check(context: AdapterContext): Promise<boolean>;
+  provision(context: AdapterContext): Promise<ProvisionResult>;
+  getRequiredTools(): string[];
+}
+
+export interface AdapterRegistry {
+  [key: string]: ServiceAdapter;
+}
+`;
+}
+function packageJsonTemplate(packageName) {
+    return JSON.stringify({
+        name: packageName,
+        version: "0.1.0",
+        description: `kit adapter plugin for ${packageName}`,
+        type: "module",
+        exports: {
+            ".": {
+                types: "./dist/index.d.ts",
+                default: "./dist/index.js",
+            },
+        },
+        files: ["dist", "!dist/**/*.test.*", "README.md"],
+        scripts: {
+            build: "tsc",
+            test: "node --test dist/*.test.js",
+        },
+        // sandstream-kit-adapter-sdk types are bundled in src/types/adapter-sdk.d.ts so this
+        // plugin builds without any registry dependencies. Once sandstream-kit-adapter-sdk is
+        // published, add it here:  peerDependencies: { "sandstream-kit-adapter-sdk": ">=0.1.0" }
+        devDependencies: {
+            "@types/node": "^22.0.0",
+            typescript: "^5.9.3",
+        },
+    }, null, 2) + "\n";
+}
+function tsconfigTemplate() {
+    return JSON.stringify({
+        compilerOptions: {
+            target: "ES2022",
+            module: "Node16",
+            moduleResolution: "Node16",
+            outDir: "dist",
+            rootDir: "src",
+            strict: true,
+            declaration: true,
+            declarationMap: true,
+            sourceMap: true,
+            // baseUrl + paths: maps sandstream-kit-adapter-sdk to the bundled type stub so the
+            // plugin builds without installing the SDK package. Once sandstream-kit-adapter-sdk is
+            // published to npm, remove these two entries and install the real package.
+            baseUrl: "src",
+            paths: {
+                "sandstream-kit-adapter-sdk": ["types/adapter-sdk.d.ts"],
+            },
+        },
+        include: ["src"],
+    }, null, 2) + "\n";
+}
+function adapterTemplate(adapterName, serviceName) {
+    return `import type { ServiceAdapter, AdapterContext, ProvisionResult } from "sandstream-kit-adapter-sdk";
+
+export const ${adapterName}: ServiceAdapter = {
+  name: "${serviceName}/deploy",
+  description: "TODO: describe what this adapter provisions",
+
+  // Return CLI tool names required for this adapter.
+  // Return an empty array for API-based adapters (no CLI needed).
+  getRequiredTools(): string[] {
+    return [];
+  },
+
+  // Return true if the service is already provisioned.
+  async check(context: AdapterContext): Promise<boolean> {
+    return !!context.existingEnv["MY_SERVICE_KEY"];
+  },
+
+  // Provision the service. Should be idempotent.
+  async provision(context: AdapterContext): Promise<ProvisionResult> {
+    const key = context.existingEnv["MY_SERVICE_KEY"];
+
+    // Key-reuse pattern: return existing key if already set
+    if (key) {
+      return {
+        success: true,
+        message: "MY_SERVICE_KEY already configured",
+        secrets: { MY_SERVICE_KEY: key },
+      };
+    }
+
+    // TODO: implement provisioning logic
+    return {
+      success: false,
+      error: "Missing MY_SERVICE_KEY",
+      message: [
+        "Set MY_SERVICE_KEY in .env.local:",
+        "1. Visit https://example.com/dashboard/api-keys",
+        "2. Create a new API key",
+        "3. Add to .env.local: MY_SERVICE_KEY=your_key_here",
+      ].join("\\n"),
+    };
+  },
+};
+`;
+}
+function testTemplate(adapterName, serviceName) {
+    const importName = adapterName;
+    return `import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ${importName} } from "./${serviceName}.js";
+
+const ctx = (env: Record<string, string> = {}) => ({
+  projectPath: "/tmp/test-project",
+  projectName: "test-project",
+  existingEnv: env,
+});
+
+describe("${importName}", () => {
+  it("has correct name", () => {
+    assert.equal(${importName}.name, "${serviceName}/deploy");
+  });
+
+  it("check returns false when key is absent", async () => {
+    assert.equal(await ${importName}.check(ctx()), false);
+  });
+
+  it("check returns true when key is present", async () => {
+    assert.equal(await ${importName}.check(ctx({ MY_SERVICE_KEY: "test" })), true);
+  });
+
+  it("provision returns error when key is missing", async () => {
+    const result = await ${importName}.provision(ctx());
+    assert.equal(result.success, false);
+    assert.ok(result.error);
+  });
+
+  it("provision returns existing key when already set", async () => {
+    const result = await ${importName}.provision(ctx({ MY_SERVICE_KEY: "sk_test" }));
+    assert.equal(result.success, true);
+    assert.equal(result.secrets?.["MY_SERVICE_KEY"], "sk_test");
+  });
+});
+`;
+}
+function indexTemplate(adapterName, shortName) {
+    return `export { ${adapterName} as adapter } from "./${shortName}.js";\n`;
+}
+function readmeTemplate(packageName, shortName) {
+    return `# ${packageName}
+
+[kit](https://github.com/sandstream/kit) adapter plugin for ${shortName}.
+
+## Installation
+
+\`\`\`bash
+npm install --save-dev ${packageName}
+\`\`\`
+
+Then register in your \`package.json\`:
+
+\`\`\`json
+{
+  "kitPlugins": ["${packageName}"]
+}
+\`\`\`
+
+## Usage
+
+\`\`\`bash
+kit add ${shortName}/deploy
+\`\`\`
+
+## Development
+
+See [PLUGIN_AUTHORING.md](https://github.com/sandstream/kit/blob/main/PLUGIN_AUTHORING.md) for the full plugin authoring guide.
+`;
+}
+//# sourceMappingURL=create-plugin.js.map

package/dist/create-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-plugin.js","sourceRoot":"","sources":["../src/create-plugin.ts"],"names":[],"mappings":"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"}