blogwright-core 0.1.0

package/dist/ports.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Repo-owned ports shared across packages. Domain code depends on these
+ * interfaces; adapters (see `adapters/`) implement them against real
+ * infrastructure and are constructed only at a composition root.
+ */
+/**
+ * File access in domain vocabulary. Paths are platform paths (absolute in
+ * practice); implementations raise {@link FileNotFoundError} for absent files
+ * so callers can branch on absence without knowing adapter error codes.
+ */
+export interface FileSystem {
+    /** Read a UTF-8 text file. Throws {@link FileNotFoundError} when absent. */
+    readText(path: string): Promise<string>;
+    /** Read a file's raw bytes. Throws {@link FileNotFoundError} when absent. */
+    readBytes(path: string): Promise<Uint8Array>;
+    /** Write a UTF-8 text file, creating parent directories as needed. */
+    writeText(path: string, text: string): Promise<void>;
+    /** True when a file or directory exists at the path. */
+    exists(path: string): Promise<boolean>;
+    /**
+     * List every file under `dir` recursively as sorted, `dir`-relative paths.
+     * Throws {@link FileNotFoundError} when `dir` does not exist.
+     */
+    listFiles(dir: string): Promise<string[]>;
+}
+/**
+ * The operator's terminal in domain vocabulary: leveled line output plus one
+ * question/answer primitive. `isInteractive` reflects TTY attachment, captured
+ * once when the adapter is constructed; callers key formatting (color) and
+ * prompting decisions off it.
+ */
+export interface Terminal {
+    /** True when the session has an interactive TTY on both input and output. */
+    readonly isInteractive: boolean;
+    /** Write one line to standard output. */
+    write(line: string): void;
+    /** Write one line to standard error. */
+    error(line: string): void;
+    /**
+     * Show a transient single-line status (elapsed time, progress). Each call
+     * replaces the previous status; the empty string clears it. Adapters that
+     * cannot rewrite a line (piped output, CI, plain mode) make this a no-op,
+     * so callers must still emit durable lines for those sessions.
+     */
+    status(line: string): void;
+    /** Show `prompt` and resolve with the operator's answer (newline excluded). */
+    question(prompt: string): Promise<string>;
+}
+/** Raised by {@link FileSystem} implementations when a path has no file. */
+export declare class FileNotFoundError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}

package/dist/ports.js

@@ -0,0 +1,15 @@
+/**
+ * Repo-owned ports shared across packages. Domain code depends on these
+ * interfaces; adapters (see `adapters/`) implement them against real
+ * infrastructure and are constructed only at a composition root.
+ */
+/** Raised by {@link FileSystem} implementations when a path has no file. */
+export class FileNotFoundError extends Error {
+    path;
+    constructor(path) {
+        super(`file not found: ${path}`);
+        this.name = 'FileNotFoundError';
+        this.path = path;
+    }
+}
+//# sourceMappingURL=ports.js.map

package/dist/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../src/ports.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA+CH,4EAA4E;AAC5E,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,IAAI,CAAS;IAEtB,YAAY,IAAY;QACtB,KAAK,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/repo-root.d.ts

@@ -0,0 +1,8 @@
+import type { FileSystem } from 'blogwright-core';
+/**
+ * Locate the site repo root by walking up to the VCS directory (`.git`, which is
+ * a file in worktrees, or `.jj`). The pds commands read/write repo files
+ * (public/, src/) and the deploy zips `git ls-files` output, so the CLI must
+ * anchor on the checkout root regardless of the invocation directory.
+ */
+export declare function findRepoRoot(fs: FileSystem, start?: string): Promise<string>;

package/dist/repo-root.js

@@ -0,0 +1,20 @@
+import { dirname, join, resolve } from 'node:path';
+/**
+ * Locate the site repo root by walking up to the VCS directory (`.git`, which is
+ * a file in worktrees, or `.jj`). The pds commands read/write repo files
+ * (public/, src/) and the deploy zips `git ls-files` output, so the CLI must
+ * anchor on the checkout root regardless of the invocation directory.
+ */
+export async function findRepoRoot(fs, start = process.cwd()) {
+    let dir = resolve(start);
+    for (;;) {
+        if ((await fs.exists(join(dir, '.git'))) || (await fs.exists(join(dir, '.jj'))))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir) {
+            throw new Error(`could not find the repo root (no .git or .jj above ${start})`);
+        }
+        dir = parent;
+    }
+}
+//# sourceMappingURL=repo-root.js.map

package/dist/repo-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-root.js","sourceRoot":"","sources":["../src/repo-root.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAInD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,EAAc,EAAE,KAAK,GAAG,OAAO,CAAC,GAAG,EAAE;IACtE,IAAI,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IACzB,SAAS,CAAC;QACR,IAAI,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QAC5F,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,sDAAsD,KAAK,GAAG,CAAC,CAAC;QAClF,CAAC;QACD,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/state.d.ts

@@ -0,0 +1,23 @@
+import type { S3Client } from './aws/s3.js';
+export type ResourceOutputs = Record<string, string | number | boolean | string[]>;
+export interface OpsState {
+    version: number;
+    env: string;
+    updatedAt: string | undefined;
+    /** nodeId -> recorded outputs (ARNs, ids, domains). */
+    resources: Record<string, ResourceOutputs>;
+}
+export declare function emptyState(env: string): OpsState;
+/**
+ * S3-backed topology state. Lives at `s3://<bucket>/state/<env>.json` so it is shared
+ * across machines and is the single source of truth for what has been provisioned.
+ */
+export declare class StateStore {
+    private readonly s3;
+    private readonly bucket;
+    private readonly env;
+    constructor(s3: S3Client, bucket: string, env: string);
+    load(): Promise<OpsState>;
+    save(state: OpsState): Promise<void>;
+    delete(): Promise<void>;
+}

package/dist/state.js

@@ -0,0 +1,44 @@
+export function emptyState(env) {
+    return { version: 1, env, updatedAt: undefined, resources: {} };
+}
+function stateKey(env) {
+    return `state/${env}.json`;
+}
+/**
+ * S3-backed topology state. Lives at `s3://<bucket>/state/<env>.json` so it is shared
+ * across machines and is the single source of truth for what has been provisioned.
+ */
+export class StateStore {
+    s3;
+    bucket;
+    env;
+    constructor(s3, bucket, env) {
+        this.s3 = s3;
+        this.bucket = bucket;
+        this.env = env;
+    }
+    async load() {
+        // getObjectText returns undefined only when the object/bucket does not exist (a fresh
+        // environment). A present-but-corrupt document must NOT be silently treated as empty —
+        // that would cause duplicate-resource creation — so let a parse error surface.
+        const text = await this.s3.getObjectText(this.bucket, stateKey(this.env));
+        // Strictly undefined: a present-but-empty (zero-byte) state object is
+        // corruption, not a fresh environment, and must hit the guard below.
+        if (text === undefined)
+            return emptyState(this.env);
+        try {
+            return JSON.parse(text);
+        }
+        catch (err) {
+            throw new Error(`state/${this.env}.json in s3://${this.bucket} is not valid JSON — refusing to proceed with empty state`, { cause: err });
+        }
+    }
+    async save(state) {
+        state.updatedAt = new Date().toISOString();
+        await this.s3.putObject(this.bucket, stateKey(this.env), JSON.stringify(state, null, 2), 'application/json');
+    }
+    async delete() {
+        await this.s3.deleteObject(this.bucket, stateKey(this.env)).catch(() => undefined);
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAYA,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;AAClE,CAAC;AAED,SAAS,QAAQ,CAAC,GAAW;IAC3B,OAAO,SAAS,GAAG,OAAO,CAAC;AAC7B,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,UAAU;IAEF;IACA;IACA;IAHnB,YACmB,EAAY,EACZ,MAAc,EACd,GAAW;QAFX,OAAE,GAAF,EAAE,CAAU;QACZ,WAAM,GAAN,MAAM,CAAQ;QACd,QAAG,GAAH,GAAG,CAAQ;IAC3B,CAAC;IAEJ,KAAK,CAAC,IAAI;QACR,sFAAsF;QACtF,uFAAuF;QACvF,+EAA+E;QAC/E,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1E,sEAAsE;QACtE,qEAAqE;QACrE,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpD,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAa,CAAC;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,SAAS,IAAI,CAAC,GAAG,iBAAiB,IAAI,CAAC,MAAM,2DAA2D,EACxG,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,KAAe;QACxB,KAAK,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC3C,MAAM,IAAI,CAAC,EAAE,CAAC,SAAS,CACrB,IAAI,CAAC,MAAM,EACX,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,EAClB,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAC9B,kBAAkB,CACnB,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,MAAM;QACV,MAAM,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACrF,CAAC;CACF"}

package/dist/util.d.ts

@@ -0,0 +1,15 @@
+export declare function sleep(ms: number): Promise<void>;
+export interface RetryOptions {
+    attempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    /** Predicate for whether an error is retryable (defaults to isRetryable). */
+    retryable?: (err: unknown) => boolean;
+}
+/** Retry a fn on transient AWS/network errors with exponential backoff. */
+export declare function withRetry<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;
+/** Poll `fn` until `done` returns true or the deadline passes. Returns the last value. */
+export declare function pollUntil<T>(fn: () => Promise<T>, done: (value: T) => boolean, opts: {
+    intervalMs: number;
+    timeoutMs: number;
+}): Promise<T>;

package/dist/util.js

@@ -0,0 +1,38 @@
+import { isRetryable } from './aws/errors.js';
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Retry a fn on transient AWS/network errors with exponential backoff. */
+export async function withRetry(fn, opts = {}) {
+    const attempts = opts.attempts ?? 5;
+    const base = opts.baseDelayMs ?? 200;
+    const max = opts.maxDelayMs ?? 5000;
+    const retryable = opts.retryable ?? isRetryable;
+    let lastErr;
+    for (let i = 0; i < attempts; i++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastErr = err;
+            if (i === attempts - 1 || !retryable(err))
+                throw err;
+            const delay = Math.min(max, base * 2 ** i);
+            await sleep(delay);
+        }
+    }
+    throw lastErr;
+}
+/** Poll `fn` until `done` returns true or the deadline passes. Returns the last value. */
+export async function pollUntil(fn, done, opts) {
+    const deadline = Date.now() + opts.timeoutMs;
+    let value = await fn();
+    while (!done(value)) {
+        if (Date.now() >= deadline)
+            return value;
+        await sleep(opts.intervalMs);
+        value = await fn();
+    }
+    return value;
+}
+//# sourceMappingURL=util.js.map

package/dist/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,MAAM,UAAU,KAAK,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAUD,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,EAAoB,EAAE,OAAqB,EAAE;IAC9E,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,IAAI,GAAG,CAAC;IACrC,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC;IACpC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,WAAW,CAAC;IAChD,IAAI,OAAgB,CAAC;IACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,GAAG,GAAG,CAAC;YACd,IAAI,CAAC,KAAK,QAAQ,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC;gBAAE,MAAM,GAAG,CAAC;YACrD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;YAC3C,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IACD,MAAM,OAAO,CAAC;AAChB,CAAC;AAED,0FAA0F;AAC1F,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,EAAoB,EACpB,IAA2B,EAC3B,IAA+C;IAE/C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC;IAC7C,IAAI,KAAK,GAAG,MAAM,EAAE,EAAE,CAAC;IACvB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACpB,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ;YAAE,OAAO,KAAK,CAAC;QACzC,MAAM,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC7B,KAAK,GAAG,MAAM,EAAE,EAAE,CAAC;IACrB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "blogwright-core",
+  "version": "0.1.0",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@aws-crypto/sha256-js": "^5.2.0",
+    "@aws-sdk/credential-providers": "^3.1079.0",
+    "@smithy/protocol-http": "^5.5.6",
+    "@smithy/signature-v4": "^5.6.2"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "oxlint": "^1.72.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "description": "SigV4 transport, per-service AWS HTTP clients, config, and S3 state store for blogwright",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/antstanley/blogwright.git"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "lint": "oxlint src",
+    "test": "vitest run"
+  }
+}