@jordanalec/dtk 1.0.5 → 1.0.7

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/cli.js

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+import { createRequire } from 'module';
 import { initCommand } from './init.js';
 import { addCommand } from './add.js';
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
 const program = new Command();
 program
     .name('dtk')
     .description('Developer toolkit scaffolder')
-    .version('0.0.1');
+    .version(version);
 program.addCommand(initCommand);
 program.addCommand(addCommand);
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jordanalec/dtk",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "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/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
   };