@jordanalec/dtk 1.0.0

package/templates/init/src/lib/http.test.ts

@@ -0,0 +1,197 @@
+import { httpGet, httpPost, httpPut, httpDelete } from './http.js';
+
+jest.mock('axios');
+import axios from 'axios';
+
+const mockAxios = axios as jest.Mocked<typeof axios>;
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  mockAxios.isAxiosError.mockReturnValue(false);
+});
+
+describe('httpGet', () => {
+  it('returns the response data on success', async () => {
+    mockAxios.get.mockResolvedValue({ data: { id: 1, name: 'item' } });
+    const result = await httpGet<{ id: number; name: string }>('https://api.example.com/item');
+    expect(result).toEqual({ id: 1, name: 'item' });
+  });
+
+  it('passes headers through to axios', async () => {
+    mockAxios.get.mockResolvedValue({ data: {} });
+    await httpGet('https://api.example.com/item', { headers: { Authorization: 'Bearer tok' } });
+    expect(mockAxios.get).toHaveBeenCalledWith('https://api.example.com/item', {
+      headers: { Authorization: 'Bearer tok' },
+    });
+  });
+
+  it('normalizes an axios error using response.data.Detail', async () => {
+    const axiosError = { response: { status: 404, data: { Detail: 'Not found' } }, message: 'Request failed' };
+    mockAxios.get.mockRejectedValue(axiosError);
+    mockAxios.isAxiosError.mockReturnValue(true);
+    await expect(httpGet('https://api.example.com/item')).rejects.toThrow('HTTP 404: Not found');
+  });
+
+  it('normalizes an axios error using response.data.message when Detail is absent', async () => {
+    const axiosError = { response: { status: 500, data: { message: 'Internal error' } }, message: 'Request failed' };
+    mockAxios.get.mockRejectedValue(axiosError);
+    mockAxios.isAxiosError.mockReturnValue(true);
+    await expect(httpGet('https://api.example.com/item')).rejects.toThrow('HTTP 500: Internal error');
+  });
+
+  it('falls back to err.message when response data has no recognised error field', async () => {
+    const axiosError = { response: { status: 503, data: {} }, message: 'Service unavailable' };
+    mockAxios.get.mockRejectedValue(axiosError);
+    mockAxios.isAxiosError.mockReturnValue(true);
+    await expect(httpGet('https://api.example.com/item')).rejects.toThrow('HTTP 503: Service unavailable');
+  });
+
+  it('rethrows a plain Error unchanged when it is not an axios error', async () => {
+    const err = new Error('network failure');
+    mockAxios.get.mockRejectedValue(err);
+    await expect(httpGet('https://api.example.com/item')).rejects.toThrow('network failure');
+  });
+});
+
+describe('httpPost', () => {
+  it('returns the response data on success', async () => {
+    mockAxios.post.mockResolvedValue({ data: { created: true } });
+    const result = await httpPost('https://api.example.com/items', { name: 'new' });
+    expect(result).toEqual({ created: true });
+  });
+
+  it('passes the request body and headers to axios', async () => {
+    mockAxios.post.mockResolvedValue({ data: {} });
+    await httpPost('https://api.example.com/items', { key: 'value' }, { headers: { 'Content-Type': 'application/json' } });
+    expect(mockAxios.post).toHaveBeenCalledWith(
+      'https://api.example.com/items',
+      { key: 'value' },
+      { headers: { 'Content-Type': 'application/json' } }
+    );
+  });
+
+});
+
+describe('httpPut', () => {
+  it('returns the response data on success', async () => {
+    mockAxios.put.mockResolvedValue({ data: { updated: true } });
+    const result = await httpPut('https://api.example.com/items/1', { name: 'updated' });
+    expect(result).toEqual({ updated: true });
+  });
+
+  it('passes the request body and headers to axios', async () => {
+    mockAxios.put.mockResolvedValue({ data: {} });
+    await httpPut('https://api.example.com/items/1', { key: 'value' }, { headers: { 'Content-Type': 'application/json' } });
+    expect(mockAxios.put).toHaveBeenCalledWith(
+      'https://api.example.com/items/1',
+      { key: 'value' },
+      { headers: { 'Content-Type': 'application/json' } }
+    );
+  });
+
+});
+
+describe('httpDelete', () => {
+  it('returns the response status code on success', async () => {
+    mockAxios.delete.mockResolvedValue({ status: 204 });
+    const status = await httpDelete('https://api.example.com/item/1');
+    expect(status).toBe(204);
+  });
+});
+
+describe('retry', () => {
+  it('retries and succeeds when retryOn returns true', async () => {
+    mockAxios.get
+      .mockRejectedValueOnce(new Error('transient'))
+      .mockResolvedValueOnce({ data: { ok: true } });
+
+    const result = await httpGet('https://api.example.com/item', {
+      retry: { attempts: 1, delayMs: 0, retryOn: () => true },
+    });
+
+    expect(result).toEqual({ ok: true });
+    expect(mockAxios.get).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not retry when retryOn returns false', async () => {
+    mockAxios.get.mockRejectedValue(new Error('fatal'));
+
+    await expect(
+      httpGet('https://api.example.com/item', {
+        retry: { attempts: 3, delayMs: 0, retryOn: () => false },
+      })
+    ).rejects.toThrow('fatal');
+
+    expect(mockAxios.get).toHaveBeenCalledTimes(1);
+  });
+
+  it('exhausts all attempts and throws when retryOn always returns true', async () => {
+    mockAxios.get.mockRejectedValue(new Error('always fails'));
+
+    await expect(
+      httpGet('https://api.example.com/item', {
+        retry: { attempts: 2, delayMs: 0, retryOn: () => true },
+      })
+    ).rejects.toThrow('always fails');
+
+    expect(mockAxios.get).toHaveBeenCalledTimes(3);
+  });
+
+  it('does not retry when no retryOn predicate is provided', async () => {
+    mockAxios.get.mockRejectedValue(new Error('no predicate'));
+
+    await expect(
+      httpGet('https://api.example.com/item', {
+        retry: { attempts: 3, delayMs: 0 },
+      })
+    ).rejects.toThrow('no predicate');
+
+    expect(mockAxios.get).toHaveBeenCalledTimes(1);
+  });
+
+  it('passes the raw error to the retryOn predicate', async () => {
+    const err = new Error('check me');
+    mockAxios.get.mockRejectedValue(err);
+    const retryOn = jest.fn().mockReturnValue(false);
+
+    await expect(
+      httpGet('https://api.example.com/item', {
+        retry: { attempts: 1, delayMs: 0, retryOn },
+      })
+    ).rejects.toThrow();
+
+    expect(retryOn).toHaveBeenCalledWith(err);
+  });
+
+  it('respects exponential backoff and maxDelayMs across multiple retries', async () => {
+    mockAxios.get
+      .mockRejectedValueOnce(new Error('transient'))
+      .mockRejectedValueOnce(new Error('transient'))
+      .mockResolvedValueOnce({ data: 'recovered' });
+
+    const result = await httpGet('https://api.example.com/item', {
+      retry: {
+        attempts: 2,
+        delayMs: 0,
+        backoff: 'exponential',
+        maxDelayMs: 100,
+        retryOn: () => true,
+      },
+    });
+
+    expect(result).toBe('recovered');
+    expect(mockAxios.get).toHaveBeenCalledTimes(3);
+  });
+
+  it('does not retry when attempts is 0', async () => {
+    mockAxios.get.mockRejectedValue(new Error('fail'));
+
+    await expect(
+      httpGet('https://api.example.com/item', {
+        retry: { attempts: 0, delayMs: 0, retryOn: () => true },
+      })
+    ).rejects.toThrow('fail');
+
+    expect(mockAxios.get).toHaveBeenCalledTimes(1);
+  });
+});

package/templates/init/src/lib/http.ts

@@ -0,0 +1,81 @@
+import axios from "axios";
+import type { HttpOptions, RetryConfig } from "../types/http.js";
+
+export type { HttpOptions };
+
+function normalizeError(err: unknown): Error {
+  if (axios.isAxiosError(err)) {
+    const status = err.response?.status;
+    const data = err.response?.data;
+    const detail = data?.Detail ?? data?.message ?? err.message;
+    return new Error(`HTTP ${status}: ${detail}`);
+  }
+  return err instanceof Error ? err : new Error(String(err));
+}
+
+function resolveDelay(attempt: number, config: RetryConfig): number {
+  const base = config.delayMs ?? 1000;
+  const delay =
+    config.backoff === "exponential" ? base * Math.pow(2, attempt) : base;
+  return config.maxDelayMs !== undefined
+    ? Math.min(delay, config.maxDelayMs)
+    : delay;
+}
+
+async function executeWithRetry<T>(
+  fn: () => Promise<T>,
+  retry?: RetryConfig
+): Promise<T> {
+  const maxAttempts = retry && retry.attempts > 0 ? retry.attempts : 0;
+  let lastErr: unknown;
+
+  for (let attempt = 0; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      const isLast = attempt === maxAttempts;
+      const shouldRetry = !isLast && !!retry?.retryOn?.(err);
+      if (!shouldRetry) break;
+      await new Promise((r) => setTimeout(r, resolveDelay(attempt, retry!)));
+    }
+  }
+
+  throw normalizeError(lastErr);
+}
+
+export async function httpGet<T>(url: string, options?: HttpOptions): Promise<T> {
+  return executeWithRetry(
+    () => axios.get<T>(url, { headers: options?.headers }).then((r) => r.data),
+    options?.retry
+  );
+}
+
+export async function httpPost<TBody, TResponse>(
+  url: string,
+  body: TBody,
+  options?: HttpOptions
+): Promise<TResponse> {
+  return executeWithRetry(
+    () => axios.post<TResponse>(url, body, { headers: options?.headers }).then((r) => r.data),
+    options?.retry
+  );
+}
+
+export async function httpPut<TBody, TResponse>(
+  url: string,
+  body: TBody,
+  options?: HttpOptions
+): Promise<TResponse> {
+  return executeWithRetry(
+    () => axios.put<TResponse>(url, body, { headers: options?.headers }).then((r) => r.data),
+    options?.retry
+  );
+}
+
+export async function httpDelete(url: string, options?: HttpOptions): Promise<number> {
+  return executeWithRetry(
+    () => axios.delete(url, { headers: options?.headers }).then((r) => r.status),
+    options?.retry
+  );
+}

package/templates/init/src/lib/oauth.test.ts

@@ -0,0 +1,61 @@
+import { clientCredentials } from './oauth.js';
+
+jest.mock('./http.js');
+import { httpPost } from './http.js';
+
+const mockHttpPost = jest.mocked(httpPost);
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+describe('clientCredentials', () => {
+  const config = {
+    clientId: 'my-client',
+    clientSecret: 'my-secret',
+    tokenUrl: 'https://auth.example.com/token',
+  };
+
+  const tokenResponse = {
+    access_token: 'tok123',
+    token_type: 'Bearer',
+    expires_in: 3600,
+  };
+
+  it('posts to the tokenUrl and returns the token response', async () => {
+    mockHttpPost.mockResolvedValue(tokenResponse);
+    const result = await clientCredentials(config);
+    expect(result).toEqual(tokenResponse);
+    expect(mockHttpPost).toHaveBeenCalledWith(
+      config.tokenUrl,
+      expect.any(URLSearchParams),
+      { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } }
+    );
+  });
+
+  it('sends client_id, client_secret, and grant_type in the body', async () => {
+    mockHttpPost.mockResolvedValue(tokenResponse);
+    await clientCredentials(config);
+
+    const body = mockHttpPost.mock.calls[0][1] as URLSearchParams;
+    expect(body.get('grant_type')).toBe('client_credentials');
+    expect(body.get('client_id')).toBe('my-client');
+    expect(body.get('client_secret')).toBe('my-secret');
+  });
+
+  it('includes scope in the body when provided', async () => {
+    mockHttpPost.mockResolvedValue(tokenResponse);
+    await clientCredentials({ ...config, scope: 'openid profile' });
+
+    const body = mockHttpPost.mock.calls[0][1] as URLSearchParams;
+    expect(body.get('scope')).toBe('openid profile');
+  });
+
+  it('omits scope from the body when not provided', async () => {
+    mockHttpPost.mockResolvedValue(tokenResponse);
+    await clientCredentials(config);
+
+    const body = mockHttpPost.mock.calls[0][1] as URLSearchParams;
+    expect(body.has('scope')).toBe(false);
+  });
+});

package/templates/init/src/lib/oauth.ts

@@ -0,0 +1,15 @@
+import { httpPost } from "./http.js";
+import type { OAuthConfig, TokenResponse } from "../types/oauth.js";
+
+export async function clientCredentials(config: OAuthConfig): Promise<TokenResponse> {
+  const params = new URLSearchParams({
+    grant_type: "client_credentials",
+    client_id: config.clientId,
+    client_secret: config.clientSecret,
+    ...(config.scope ? { scope: config.scope } : {}),
+  });
+
+  return httpPost<URLSearchParams, TokenResponse>(config.tokenUrl, params, {
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+  });
+}

package/templates/init/src/lib/token.ts

@@ -0,0 +1,5 @@
+export function getClaimValues(token: string): Record<string, string> {
+  const payload = token.split(".")[1];
+  const decoded = Buffer.from(payload, "base64").toString("utf-8");
+  return JSON.parse(decoded);
+}

package/templates/init/src/load-env.ts

@@ -0,0 +1,4 @@
+import * as dotenv from "dotenv";
+
+dotenv.config({ path: ".env" });
+dotenv.config({ path: ".env.local", override: true });

package/templates/init/src/runbooks/example.ts

@@ -0,0 +1,33 @@
+import axios from 'axios';
+import "../load-env.js";
+import { suite } from "../suite.js";
+
+interface GitHubUser {
+  login: string;
+  name: string;
+  public_repos: number;
+  followers: number;
+}
+
+await suite()
+  .step("fetch-github-user", async (ctx) => {
+    const user = await ctx.http.get<GitHubUser>(
+      "https://api.github.com/users/torvalds",
+      {
+        headers: { "User-Agent": "dtk-runbook" },
+        retry: {
+          attempts: 3,
+          backoff: "exponential",
+          delayMs: 500,
+          maxDelayMs: 5000,
+          retryOn: (err) =>
+            axios.isAxiosError(err) &&
+            [429, 503].includes(err.response?.status ?? 0),
+        },
+      }
+    );
+    console.log(`login: ${user.login}`);
+    console.log(`name: ${user.name}`);
+    return user;
+  })
+  .run("throwOnError");

package/templates/init/src/suite.test.ts

@@ -0,0 +1,94 @@
+import { suite } from './suite.js';
+
+// suppress the [OK] / [FAIL] console output during tests
+beforeEach(() => {
+  jest.spyOn(console, 'log').mockImplementation(() => {});
+  jest.spyOn(console, 'error').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
+describe('suite runner', () => {
+  it('executes steps in the order they were defined', async () => {
+    const order: number[] = [];
+    await suite()
+      .step('first',  async () => { order.push(1); })
+      .step('second', async () => { order.push(2); })
+      .step('third',  async () => { order.push(3); })
+      .run("stopOnError");
+    expect(order).toEqual([1, 2, 3]);
+  });
+
+  it('stores each step return value in ctx.outputs under the step name', async () => {
+    let captured: unknown;
+    await suite()
+      .step('produce', async () => ({ value: 42 }))
+      .step('consume', async (ctx) => { captured = ctx.outputs['produce']; })
+      .run("throwOnError");
+    expect(captured).toEqual({ value: 42 });
+  });
+
+  it('makes all prior outputs available to each step', async () => {
+    const seen: unknown[] = [];
+    await suite()
+      .step('a', async () => 'alpha')
+      .step('b', async () => 'beta')
+      .step('c', async (ctx) => { seen.push(ctx.outputs['a'], ctx.outputs['b']); })
+      .run("throwOnError");
+    expect(seen).toEqual(['alpha', 'beta']);
+  });
+
+  describe('ThrowOnError', () => {
+    it('throws when a step fails', async () => {
+      await expect(
+        suite()
+          .step('fail', async () => { throw new Error('boom'); })
+          .run("throwOnError")
+      ).rejects.toThrow('boom');
+    });
+
+    it('does not execute steps after the failure', async () => {
+      const ran: string[] = [];
+      await suite()
+        .step('ok',      async () => { ran.push('ok'); })
+        .step('fail',    async () => { throw new Error('boom'); })
+        .step('skipped', async () => { ran.push('skipped'); })
+        .run("throwOnError")
+        .catch(() => {});
+      expect(ran).toEqual(['ok']);
+    });
+  });
+
+  describe('StopOnError', () => {
+    it('does not throw when a step fails', async () => {
+      await expect(
+        suite()
+          .step('fail', async () => { throw new Error('non-fatal'); })
+          .run("stopOnError")
+      ).resolves.toBeUndefined();
+    });
+
+    it('stops executing after the failure (does not skip to next step)', async () => {
+      const ran: string[] = [];
+      await suite()
+        .step('ok',      async () => { ran.push('ok'); })
+        .step('fail',    async () => { throw new Error('stop'); })
+        .step('skipped', async () => { ran.push('skipped'); })
+        .run("stopOnError");
+      expect(ran).toEqual(['ok']);
+      expect(ran).not.toContain('skipped');
+    });
+
+    it('logs the failure to console.error', async () => {
+      await suite()
+        .step('fail', async () => { throw new Error('something broke'); })
+        .run("stopOnError");
+      expect(console.error).toHaveBeenCalledWith(
+        expect.stringContaining('something broke')
+      );
+    });
+  });
+
+});

package/templates/init/src/suite.ts

@@ -0,0 +1,70 @@
+import { clientCredentials } from "./lib/oauth.js";
+import { getClaimValues } from "./lib/token.js";
+import { httpGet, httpPost, httpPut, httpDelete } from "./lib/http.js";
+import { basicAuth } from "./lib/basic-auth.js";
+import { bearerToken } from "./lib/bearer-token.js";
+// dtk:imports
+
+import type { OAuthConfig, BasicAuthConfig, BearerTokenConfig, StepContext, StepFn, Step, SuiteRunOption } from "./types/suite.js";
+
+export type { SuiteRunOption };
+
+class Suite {
+  private steps: Step[] = [];
+  private oauthConfig?: OAuthConfig;
+  private basicAuthConfig?: BasicAuthConfig;
+  private bearerTokenConfig?: BearerTokenConfig;
+  // dtk:configs
+
+  oauth(config: OAuthConfig): this { this.oauthConfig = config; return this; }
+  basicAuth(config: BasicAuthConfig): this { this.basicAuthConfig = config; return this; }
+  bearerToken(config: BearerTokenConfig): this { this.bearerTokenConfig = config; return this; }
+  // dtk:methods
+
+  step(name: string, fn: StepFn): this {
+    this.steps.push({ name, fn });
+    return this;
+  }
+
+  private buildContext(outputs: Record<string, unknown>): StepContext {
+    const oauthConfig = this.oauthConfig;
+    return {
+      outputs,
+      auth: {
+        clientCredentials: (config?) => clientCredentials(config ?? oauthConfig!),
+        getClaimValues,
+        basicAuth: (config?) => basicAuth(config ?? this.basicAuthConfig!),
+        bearerToken: (config?) => bearerToken(config ?? this.bearerTokenConfig!),
+      },
+      http: {
+        get: httpGet,
+        post: httpPost,
+        put: httpPut,
+        delete: httpDelete,
+      },
+      services: {
+        // dtk:services
+      },
+    };
+  }
+
+  async run(option: SuiteRunOption): Promise<void> {
+    const outputs: Record<string, unknown> = {};
+    const ctx = this.buildContext(outputs);
+    for (const step of this.steps) {
+      try {
+        outputs[step.name] = await step.fn(ctx);
+        console.log(`[OK] ${step.name}`);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[FAIL] ${step.name}: ${message}`);
+        if (option === "throwOnError") throw err;
+        else break;
+      }
+    }
+  }
+}
+
+export function suite(): Suite {
+  return new Suite();
+}

package/templates/init/src/types/http.ts

@@ -0,0 +1,12 @@
+export interface RetryConfig {
+  attempts: number;
+  backoff?: "fixed" | "exponential";
+  delayMs?: number;
+  maxDelayMs?: number;
+  retryOn?: (err: unknown) => boolean;
+}
+
+export interface HttpOptions {
+  headers?: Record<string, string>;
+  retry?: RetryConfig;
+}

package/templates/init/src/types/oauth.ts

@@ -0,0 +1,13 @@
+export interface OAuthConfig {
+  clientId: string;
+  clientSecret: string;
+  tokenUrl: string;
+  scope?: string;
+}
+
+export interface TokenResponse {
+  access_token: string;
+  token_type: string;
+  expires_in?: number;
+  scope?: string;
+}

package/templates/init/src/types/suite.ts

@@ -0,0 +1,37 @@
+import type { HttpOptions } from "./http.js";
+import type { OAuthConfig, TokenResponse } from "./oauth.js";
+// dtk:type-imports
+
+export type { HttpOptions };
+
+export interface BasicAuthConfig { username: string; password: string; }
+export interface BearerTokenConfig { token: string; prefix: string; }
+export type { OAuthConfig, TokenResponse };
+
+export interface StepContext {
+  outputs: Record<string, unknown>;
+  auth: {
+    clientCredentials(config?: OAuthConfig): Promise<TokenResponse>;
+    getClaimValues(token: string): Record<string, string>;
+    basicAuth(config?: BasicAuthConfig): Promise<string>;
+    bearerToken(config?: BearerTokenConfig): Promise<string>;
+  };
+  http: {
+    get<T>(url: string, options?: HttpOptions): Promise<T>;
+    post<TBody, TResponse>(url: string, body: TBody, options?: HttpOptions): Promise<TResponse>;
+    put<TBody, TResponse>(url: string, body: TBody, options?: HttpOptions): Promise<TResponse>;
+    delete(url: string, options?: HttpOptions): Promise<number>;
+  };
+  services: {
+    // dtk:service-types
+  };
+}
+
+export type StepFn = (ctx: StepContext) => Promise<unknown>;
+
+export interface Step {
+  name: string;
+  fn: StepFn;
+}
+
+export type SuiteRunOption = "throwOnError" | "stopOnError";

package/templates/init/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["node", "jest"]
+  },
+  "include": ["src"]
+}

package/templates/init/tsconfig.test.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "types": ["jest", "node"]
+  }
+}

package/templates/plugins/aws-dynamo/env.txt

@@ -0,0 +1,2 @@
+DYNAMO_TABLE_NAME=
+AWS_REGION=