@jordanalec/dtk 1.0.4 → 1.0.6

package/README.md

@@ -678,6 +678,7 @@ my-project/
       basic-auth.ts       # base64 Basic auth header builder
       bearer-token.ts     # Bearer token header builder
       token.ts            # JWT claim decoder
+      file.ts             # readFile / writeFile / copyFile / moveFile / deleteFile / listDir etc.
     types/
       suite.ts            # StepContext, SuiteRunOption string union, auth types -- do not delete sentinel comments
       oauth.ts            # OAuthConfig, TokenResponse

package/dist/init.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, '../templates');
-const ROOT_FILES = ['.env.template', 'tsconfig.json', 'tsconfig.test.json', 'jest.config.ts', 'README.md', 'GUIDE.md'];
+const ROOT_FILES = ['.env.template', 'tsconfig.json', 'tsconfig.test.json', 'jest.config.cjs', 'README.md', 'GUIDE.md'];
 export const initCommand = new Command('init')
     .description('Scaffold a new dtk project in the current directory')
     .argument('[name]', 'project name (defaults to the current directory name)')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jordanalec/dtk",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "CLI scaffolding tool for generating self-contained TypeScript runbook projects",
   "keywords": [
     "cli",

package/templates/init/GUIDE.md

@@ -512,7 +512,9 @@ All shared type definitions: `StepContext`, `StepFn`, `Step`, the `SuiteRunOptio
 
 ### `src/lib/http.ts`
 
-Axios wrapper. Provides `httpGet`, `httpPost`, `httpPut`, and `httpDelete`. Normalises errors into plain `Error` objects with readable messages. Use this inside service factories instead of calling axios directly.
+Axios wrapper. Provides `httpGet`, `httpPost`, `httpPut`, and `httpDelete`. Normalises errors into plain `Error` objects with readable messages (`HTTP 404: ...`). Use this inside service factories instead of calling axios directly.
+
+All four functions accept an optional `HttpOptions` argument with `headers` and `retry`. When `retry` is set, failed requests are retried up to `attempts` times with either fixed or exponential backoff (`delayMs`, `maxDelayMs`). Provide a `retryOn` predicate to control which errors trigger a retry. `httpDelete` returns the HTTP status code as a `number`.
 
 ### `src/lib/oauth.ts`
 
@@ -530,6 +532,10 @@ Returns `<prefix> <token>` (e.g. `Bearer sk-abc123`) ready to use as an `Authori
 
 `getClaimValues(token)` decodes the payload of a JWT and returns the claims as a plain object. Does not verify the signature.
 
+### `src/lib/file.ts`
+
+File system utilities. Provides `readFile`, `readJson<T>`, `writeFile`, `writeJson`, `appendFile`, `fileExists`, `deleteFile`, `ensureDir`, `copyFile`, `moveFile`, and `listDir`. All functions wrap `node:fs/promises` and normalise errors into readable messages (`file not found`, `permission denied`, `path is a directory`). Parent directories are created automatically on write, append, and copy.
+
 ### `src/load-env.ts`
 
 Loads `.env` then `.env.local` (local overrides). Import this as the very first line of every runbook.

package/templates/init/README.md

@@ -51,7 +51,7 @@ See `GUIDE.md` for full details.
 src/
   suite.ts          # core runner -- extend this with custom services
   load-env.ts       # dotenv bootstrap -- import first in every runbook
-  lib/              # HTTP client, OAuth, auth helpers
+  lib/              # HTTP client, OAuth, auth helpers, file system utilities
   types/            # type definitions
   services/         # service factories added by plugins or custom code
   runbooks/         # your runbook scripts

package/templates/init/{jest.config.ts → jest.config.cjs}

@@ -1,10 +1,8 @@
-import type { Config } from 'jest';
-
-const config: Config = {
+/** @type {import('jest').Config} */
+const config = {
   preset: 'ts-jest',
   testEnvironment: 'node',
   moduleNameMapper: {
-    // source files use .js extensions in imports; map them to .ts for jest
     '^(\\.{1,2}/.*)\\.js$': '$1',
   },
   transform: {
@@ -16,4 +14,4 @@ const config: Config = {
   testMatch: ['**/*.test.ts'],
 };
 
-export default config;
+module.exports = config;

package/templates/init/package.json

@@ -4,7 +4,7 @@
   "type": "module",
   "scripts": {
     "runbook:example": "tsx src/runbooks/example.ts",
-    "test": "node node_modules/jest/bin/jest.js"
+    "test": "jest"
   },
   "dependencies": {
     "axios": "^1.6.0",

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

@@ -0,0 +1,194 @@
+import { readFile, readJson, writeFile, writeJson, appendFile, fileExists, deleteFile, ensureDir, copyFile, moveFile, listDir } from './file.js';
+
+jest.mock('node:fs/promises');
+import * as fs from 'node:fs/promises';
+
+const mockFs = fs as jest.Mocked<typeof fs>;
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+describe('readFile', () => {
+  it('returns file content as a string', async () => {
+    mockFs.readFile.mockResolvedValue('hello world' as any);
+    const result = await readFile('/tmp/test.txt');
+    expect(result).toBe('hello world');
+    expect(mockFs.readFile).toHaveBeenCalledWith('/tmp/test.txt', 'utf-8');
+  });
+
+  it('throws a friendly message on ENOENT', async () => {
+    mockFs.readFile.mockRejectedValue(Object.assign(new Error('no such file'), { code: 'ENOENT' }));
+    await expect(readFile('/tmp/missing.txt')).rejects.toThrow('file not found: /tmp/missing.txt');
+  });
+
+  it('throws a friendly message on EACCES', async () => {
+    mockFs.readFile.mockRejectedValue(Object.assign(new Error('permission denied'), { code: 'EACCES' }));
+    await expect(readFile('/tmp/secret.txt')).rejects.toThrow('permission denied: /tmp/secret.txt');
+  });
+
+  it('throws a friendly message on EISDIR', async () => {
+    mockFs.readFile.mockRejectedValue(Object.assign(new Error('is a directory'), { code: 'EISDIR' }));
+    await expect(readFile('/tmp/adir')).rejects.toThrow('path is a directory: /tmp/adir');
+  });
+
+  it('includes the error code for unrecognised fs errors', async () => {
+    mockFs.readFile.mockRejectedValue(Object.assign(new Error('device full'), { code: 'ENOSPC' }));
+    await expect(readFile('/tmp/test.txt')).rejects.toThrow('ENOSPC:');
+  });
+
+  it('rethrows a plain Error unchanged when no code is present', async () => {
+    mockFs.readFile.mockRejectedValue(new Error('unexpected'));
+    await expect(readFile('/tmp/test.txt')).rejects.toThrow('unexpected');
+  });
+});
+
+describe('readJson', () => {
+  it('parses and returns JSON content', async () => {
+    mockFs.readFile.mockResolvedValue('{"id":1,"name":"test"}' as any);
+    const result = await readJson<{ id: number; name: string }>('/tmp/data.json');
+    expect(result).toEqual({ id: 1, name: 'test' });
+  });
+
+  it('throws when the file contains invalid JSON', async () => {
+    mockFs.readFile.mockResolvedValue('not json' as any);
+    await expect(readJson('/tmp/bad.json')).rejects.toThrow('invalid JSON in file: /tmp/bad.json');
+  });
+
+  it('propagates read errors from readFile', async () => {
+    mockFs.readFile.mockRejectedValue(Object.assign(new Error('no such file'), { code: 'ENOENT' }));
+    await expect(readJson('/tmp/missing.json')).rejects.toThrow('file not found: /tmp/missing.json');
+  });
+});
+
+describe('writeFile', () => {
+  it('creates the parent directory then writes the content', async () => {
+    mockFs.mkdir.mockResolvedValue(undefined);
+    mockFs.writeFile.mockResolvedValue(undefined);
+    await writeFile('/tmp/dir/test.txt', 'content');
+    expect(mockFs.mkdir).toHaveBeenCalledWith('/tmp/dir', { recursive: true });
+    expect(mockFs.writeFile).toHaveBeenCalledWith('/tmp/dir/test.txt', 'content', 'utf-8');
+  });
+
+  it('throws a friendly message on write error', async () => {
+    mockFs.mkdir.mockResolvedValue(undefined);
+    mockFs.writeFile.mockRejectedValue(Object.assign(new Error('permission denied'), { code: 'EACCES' }));
+    await expect(writeFile('/tmp/test.txt', 'content')).rejects.toThrow('permission denied: /tmp/test.txt');
+  });
+});
+
+describe('writeJson', () => {
+  it('serialises JSON with the default indent of 2', async () => {
+    mockFs.mkdir.mockResolvedValue(undefined);
+    mockFs.writeFile.mockResolvedValue(undefined);
+    await writeJson('/tmp/data.json', { id: 1 });
+    expect(mockFs.writeFile).toHaveBeenCalledWith('/tmp/data.json', JSON.stringify({ id: 1 }, null, 2), 'utf-8');
+  });
+
+  it('uses the provided indent value', async () => {
+    mockFs.mkdir.mockResolvedValue(undefined);
+    mockFs.writeFile.mockResolvedValue(undefined);
+    await writeJson('/tmp/data.json', { id: 1 }, 4);
+    expect(mockFs.writeFile).toHaveBeenCalledWith('/tmp/data.json', JSON.stringify({ id: 1 }, null, 4), 'utf-8');
+  });
+});
+
+describe('appendFile', () => {
+  it('creates the parent directory then appends the content', async () => {
+    mockFs.mkdir.mockResolvedValue(undefined);
+    mockFs.appendFile.mockResolvedValue(undefined);
+    await appendFile('/tmp/dir/log.txt', 'new line\n');
+    expect(mockFs.mkdir).toHaveBeenCalledWith('/tmp/dir', { recursive: true });
+    expect(mockFs.appendFile).toHaveBeenCalledWith('/tmp/dir/log.txt', 'new line\n', 'utf-8');
+  });
+
+  it('throws a friendly message on append error', async () => {
+    mockFs.mkdir.mockResolvedValue(undefined);
+    mockFs.appendFile.mockRejectedValue(Object.assign(new Error('permission denied'), { code: 'EACCES' }));
+    await expect(appendFile('/tmp/log.txt', 'data')).rejects.toThrow('permission denied: /tmp/log.txt');
+  });
+});
+
+describe('fileExists', () => {
+  it('returns true when the file is accessible', async () => {
+    mockFs.access.mockResolvedValue(undefined);
+    expect(await fileExists('/tmp/exists.txt')).toBe(true);
+  });
+
+  it('returns false when access throws', async () => {
+    mockFs.access.mockRejectedValue(Object.assign(new Error('no such file'), { code: 'ENOENT' }));
+    expect(await fileExists('/tmp/missing.txt')).toBe(false);
+  });
+});
+
+describe('deleteFile', () => {
+  it('calls rm with force: true', async () => {
+    mockFs.rm.mockResolvedValue(undefined);
+    await deleteFile('/tmp/old.txt');
+    expect(mockFs.rm).toHaveBeenCalledWith('/tmp/old.txt', { force: true });
+  });
+
+  it('throws a friendly message on rm error', async () => {
+    mockFs.rm.mockRejectedValue(Object.assign(new Error('permission denied'), { code: 'EACCES' }));
+    await expect(deleteFile('/tmp/protected.txt')).rejects.toThrow('permission denied: /tmp/protected.txt');
+  });
+});
+
+describe('ensureDir', () => {
+  it('calls mkdir with recursive: true', async () => {
+    mockFs.mkdir.mockResolvedValue(undefined);
+    await ensureDir('/tmp/new/nested/dir');
+    expect(mockFs.mkdir).toHaveBeenCalledWith('/tmp/new/nested/dir', { recursive: true });
+  });
+
+  it('throws a friendly message on mkdir error', async () => {
+    mockFs.mkdir.mockRejectedValue(Object.assign(new Error('permission denied'), { code: 'EACCES' }));
+    await expect(ensureDir('/tmp/restricted')).rejects.toThrow('permission denied: /tmp/restricted');
+  });
+});
+
+describe('copyFile', () => {
+  it('creates the dest directory then copies the file', async () => {
+    mockFs.mkdir.mockResolvedValue(undefined);
+    mockFs.copyFile.mockResolvedValue(undefined);
+    await copyFile('/tmp/src.txt', '/tmp/dest/copy.txt');
+    expect(mockFs.mkdir).toHaveBeenCalledWith('/tmp/dest', { recursive: true });
+    expect(mockFs.copyFile).toHaveBeenCalledWith('/tmp/src.txt', '/tmp/dest/copy.txt');
+  });
+
+  it('throws a friendly message when the source is not found', async () => {
+    mockFs.mkdir.mockResolvedValue(undefined);
+    mockFs.copyFile.mockRejectedValue(Object.assign(new Error('no such file'), { code: 'ENOENT' }));
+    await expect(copyFile('/tmp/missing.txt', '/tmp/dest.txt')).rejects.toThrow('file not found: /tmp/missing.txt');
+  });
+});
+
+describe('moveFile', () => {
+  it('creates the dest directory then renames the file', async () => {
+    mockFs.mkdir.mockResolvedValue(undefined);
+    mockFs.rename.mockResolvedValue(undefined);
+    await moveFile('/tmp/old.txt', '/tmp/moved/new.txt');
+    expect(mockFs.mkdir).toHaveBeenCalledWith('/tmp/moved', { recursive: true });
+    expect(mockFs.rename).toHaveBeenCalledWith('/tmp/old.txt', '/tmp/moved/new.txt');
+  });
+
+  it('throws a friendly message when the source is not found', async () => {
+    mockFs.mkdir.mockResolvedValue(undefined);
+    mockFs.rename.mockRejectedValue(Object.assign(new Error('no such file'), { code: 'ENOENT' }));
+    await expect(moveFile('/tmp/missing.txt', '/tmp/new.txt')).rejects.toThrow('file not found: /tmp/missing.txt');
+  });
+});
+
+describe('listDir', () => {
+  it('returns the directory entries as strings', async () => {
+    mockFs.readdir.mockResolvedValue(['a.txt', 'b.txt', 'subdir'] as any);
+    const result = await listDir('/tmp/mydir');
+    expect(result).toEqual(['a.txt', 'b.txt', 'subdir']);
+    expect(mockFs.readdir).toHaveBeenCalledWith('/tmp/mydir');
+  });
+
+  it('throws a friendly message when the directory is not found', async () => {
+    mockFs.readdir.mockRejectedValue(Object.assign(new Error('no such file or directory'), { code: 'ENOENT' }));
+    await expect(listDir('/tmp/missing')).rejects.toThrow('file not found: /tmp/missing');
+  });
+});

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

@@ -0,0 +1,113 @@
+import {
+  readFile as fsReadFile,
+  writeFile as fsWriteFile,
+  appendFile as fsAppendFile,
+  rm,
+  mkdir,
+  copyFile as fsCopyFile,
+  rename,
+  readdir,
+  access,
+} from "node:fs/promises";
+import { dirname } from "node:path";
+
+function normalizeError(err: unknown, path: string): Error {
+  if (err instanceof Error && "code" in err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return new Error(`file not found: ${path}`);
+    if (code === "EACCES") return new Error(`permission denied: ${path}`);
+    if (code === "EISDIR") return new Error(`path is a directory: ${path}`);
+    return new Error(`${code}: ${(err as Error).message}`);
+  }
+  return err instanceof Error ? err : new Error(String(err));
+}
+
+export async function readFile(path: string): Promise<string> {
+  try {
+    return await fsReadFile(path, "utf-8");
+  } catch (err) {
+    throw normalizeError(err, path);
+  }
+}
+
+export async function readJson<T = unknown>(path: string): Promise<T> {
+  const content = await readFile(path);
+  try {
+    return JSON.parse(content) as T;
+  } catch {
+    throw new Error(`invalid JSON in file: ${path}`);
+  }
+}
+
+export async function writeFile(path: string, content: string): Promise<void> {
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    await fsWriteFile(path, content, "utf-8");
+  } catch (err) {
+    throw normalizeError(err, path);
+  }
+}
+
+export async function writeJson(path: string, data: unknown, indent = 2): Promise<void> {
+  await writeFile(path, JSON.stringify(data, null, indent));
+}
+
+export async function appendFile(path: string, content: string): Promise<void> {
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    await fsAppendFile(path, content, "utf-8");
+  } catch (err) {
+    throw normalizeError(err, path);
+  }
+}
+
+export async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function deleteFile(path: string): Promise<void> {
+  try {
+    await rm(path, { force: true });
+  } catch (err) {
+    throw normalizeError(err, path);
+  }
+}
+
+export async function ensureDir(path: string): Promise<void> {
+  try {
+    await mkdir(path, { recursive: true });
+  } catch (err) {
+    throw normalizeError(err, path);
+  }
+}
+
+export async function copyFile(src: string, dest: string): Promise<void> {
+  try {
+    await mkdir(dirname(dest), { recursive: true });
+    await fsCopyFile(src, dest);
+  } catch (err) {
+    throw normalizeError(err, src);
+  }
+}
+
+export async function moveFile(src: string, dest: string): Promise<void> {
+  try {
+    await mkdir(dirname(dest), { recursive: true });
+    await rename(src, dest);
+  } catch (err) {
+    throw normalizeError(err, src);
+  }
+}
+
+export async function listDir(path: string): Promise<string[]> {
+  try {
+    return await readdir(path);
+  } catch (err) {
+    throw normalizeError(err, path);
+  }
+}

package/templates/init/src/suite.ts

@@ -1,6 +1,7 @@
 import { clientCredentials } from "./lib/oauth.js";
 import { getClaimValues } from "./lib/token.js";
 import { httpGet, httpPost, httpPut, httpDelete } from "./lib/http.js";
+import { readFile, readJson, writeFile, writeJson, appendFile, fileExists, deleteFile, ensureDir, copyFile, moveFile, listDir } from "./lib/file.js";
 import { basicAuth } from "./lib/basic-auth.js";
 import { bearerToken } from "./lib/bearer-token.js";
 // dtk:imports
@@ -42,6 +43,19 @@ class Suite {
         put: httpPut,
         delete: httpDelete,
       },
+      file: {
+        read: readFile,
+        readJson,
+        write: writeFile,
+        writeJson,
+        append: appendFile,
+        exists: fileExists,
+        delete: deleteFile,
+        ensureDir,
+        copy: copyFile,
+        move: moveFile,
+        list: listDir,
+      },
       services: {
         // dtk:services
       },

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

@@ -22,6 +22,19 @@ export interface StepContext {
     put<TBody, TResponse>(url: string, body: TBody, options?: HttpOptions): Promise<TResponse>;
     delete(url: string, options?: HttpOptions): Promise<number>;
   };
+  file: {
+    read(path: string): Promise<string>;
+    readJson<T = unknown>(path: string): Promise<T>;
+    write(path: string, content: string): Promise<void>;
+    writeJson(path: string, data: unknown, indent?: number): Promise<void>;
+    append(path: string, content: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    delete(path: string): Promise<void>;
+    ensureDir(path: string): Promise<void>;
+    copy(src: string, dest: string): Promise<void>;
+    move(src: string, dest: string): Promise<void>;
+    list(path: string): Promise<string[]>;
+  };
   services: {
     // dtk:service-types
   };