@fgv/ks 5.1.0-25

package/src/help.ts

@@ -0,0 +1,116 @@
+import { Command } from 'commander';
+
+import { fail, Result, succeed } from '@fgv/ts-utils';
+
+export type HelpTopic = 'overview' | 'commands' | 'password' | 'template';
+
+const AVAILABLE_HELP_TOPICS: readonly HelpTopic[] = ['overview', 'commands', 'password', 'template'];
+
+const HELP_OVERVIEW: string = `ks manages ts-extras keystore files.
+
+Start here:
+  ks help overview
+  ks help commands
+  ks help password
+  ks help template
+
+Default keystore:
+  ~/.fgv-ks
+
+Common commands:
+  ks init
+  ks put <name>
+  ks get <name>
+  ks list
+  ks remove <name>
+  ks export
+  ks session`;
+
+const HELP_COMMANDS: string = `ks commands
+
+  ks init            Create a new keystore
+  ks password        Change the keystore password
+  ks put <name>      Store a secret in the keystore
+  ks get <name>      Read a secret from the keystore
+  ks list            List stored secrets
+  ks remove <name>   Remove a stored secret
+  ks export          Render a shell template from keystore secrets
+  ks session         Emit a shell export statement for the password
+  ks help [topic]    Show self-contained help on a specific topic`;
+
+const HELP_PASSWORD: string = `ks password sources
+
+Passwords may be supplied with:
+  --password-file <path>
+  --password-stdin
+  --password-env <name>
+  FGV_KS_PASSWORD
+  KS_PASSWORD
+
+If no password source is provided, ks prompts interactively.
+The session command can emit a shell export statement:
+  ks session --var FGV_KS_PASSWORD`;
+
+const HELP_TEMPLATE: string = `ks export template format
+
+Templates use simple Mustache-style variables such as {{xai}}.
+Only simple variables are supported; sections and other advanced Mustache features are rejected.
+
+Options:
+  --template-file <path>    Read the shell template from a file
+  --template-string <text>  Use an inline shell template string
+  --persist-missing         Save prompted secrets back to the keystore
+  --clipboard               Copy the rendered output to the clipboard
+
+Missing secrets referenced by the template are prompted interactively.
+Rendered values are shell-quoted before output.
+
+Example:
+  ks export --template-file ./keystore.template.sh
+  ks export --template-string 'export XAI_API_KEY={{xai}}'`;
+
+const HELP_TEXTS: Readonly<Record<HelpTopic, string>> = {
+  commands: HELP_COMMANDS,
+  overview: HELP_OVERVIEW,
+  password: HELP_PASSWORD,
+  template: HELP_TEMPLATE
+};
+
+function normalizeHelpTopic(topic: string): string {
+  return topic.trim().toLowerCase();
+}
+
+function formatAvailableTopics(): string {
+  return AVAILABLE_HELP_TOPICS.join(', ');
+}
+
+export function getHelpText(topic: string | undefined = undefined, program?: Command): Result<string> {
+  if (topic === undefined || topic.trim().length === 0) {
+    return succeed(HELP_TEXTS.overview);
+  }
+
+  const normalized = normalizeHelpTopic(topic);
+
+  if (program !== undefined) {
+    const command = program.commands.find((candidate: Command) => candidate.name() === normalized);
+    if (command !== undefined && command.name() !== 'help') {
+      return succeed(command.helpInformation());
+    }
+  }
+
+  switch (normalized) {
+    case 'help':
+    case 'overview':
+      return succeed(HELP_TEXTS.overview);
+    case 'commands':
+    case 'command':
+      return succeed(HELP_TEXTS.commands);
+    case 'password':
+    case 'passwords':
+      return succeed(HELP_TEXTS.password);
+    case 'template':
+      return succeed(HELP_TEXTS.template);
+    default:
+      return fail(`Unknown help topic '${topic}'. Available topics: ${formatAvailableTopics()}`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * \@fgv/ks — CLI tool for managing ts-extras keystore files.
+ *
+ * @packageDocumentation
+ */
+
+export { KsCli } from './app';
+export {
+  changeKeystorePassword,
+  createKeystore,
+  loadKeystoreFile,
+  listSecrets,
+  openKeystore,
+  readSecret,
+  removeSecret,
+  resolveKeystorePath,
+  saveKeystoreFile,
+  storeSecret
+} from './keystore';
+export { defaultKeystorePath, copyTextToClipboard, promptHidden, readAllFromStdin, readTextFile } from './io';
+export { extractTemplateVariables, renderShellTemplate, shellQuote } from './template';

package/src/io.ts

@@ -0,0 +1,179 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import * as readline from 'readline';
+
+import clipboardy from 'clipboardy';
+import { FileTree, FileTree as FileTreeNamespace } from '@fgv/ts-json-base';
+import { Result, captureAsyncResult, captureResult, fail, succeed } from '@fgv/ts-utils';
+
+function expandHome(filePath: string): string {
+  if (!filePath.startsWith('~')) {
+    return filePath;
+  }
+
+  const home = os.homedir();
+  if (filePath === '~') {
+    return home;
+  }
+
+  if (filePath.startsWith('~/')) {
+    return path.join(home, filePath.substring(2));
+  }
+
+  return filePath;
+}
+
+export function resolvePath(filePath: string): string {
+  return path.resolve(expandHome(filePath));
+}
+
+export function defaultKeystorePath(): string {
+  return path.join(os.homedir(), '.fgv-ks');
+}
+
+export function readTextFile(filePath: string): Result<string> {
+  const resolvedPath = resolvePath(filePath);
+  return FileTree.forFilesystem().onSuccess((tree) =>
+    tree.getFile(resolvedPath).onSuccess((file) => file.getRawContents())
+  );
+}
+
+export function writeTextFile(filePath: string, contents: string): Result<string> {
+  const resolvedPath = resolvePath(filePath);
+  const directoryPath = path.dirname(resolvedPath);
+  const fileName = path.basename(resolvedPath);
+
+  return FileTree.forFilesystem({ mutable: true }).onSuccess((tree) => {
+    const accessors = tree.hal;
+    if (!FileTreeNamespace.isMutableAccessors(accessors)) {
+      return fail(`Unable to write '${resolvedPath}': filesystem access is read-only`);
+    }
+
+    return accessors.createDirectory(directoryPath).onSuccess(() =>
+      tree.getDirectory(directoryPath).onSuccess((directory) => {
+        if (!FileTreeNamespace.isMutableDirectoryItem(directory)) {
+          return fail(`Unable to write '${resolvedPath}': directory is not mutable`);
+        }
+
+        const tmpFileName = `${fileName}.tmp`;
+        return directory.createChildFile(tmpFileName, contents).onSuccess(() =>
+          captureResult(() => {
+            fs.renameSync(path.join(directoryPath, tmpFileName), resolvedPath);
+            return resolvedPath;
+          })
+        );
+      })
+    );
+  });
+}
+
+export async function readAllFromStdin(): Promise<Result<string>> {
+  const result = await captureAsyncResult(async () => {
+    const chunks: string[] = [];
+    const input = process.stdin;
+    input.setEncoding('utf8');
+    input.resume();
+
+    for await (const chunk of input) {
+      chunks.push(String(chunk));
+    }
+
+    return chunks.join('');
+  });
+
+  return result.withErrorFormat((message: string) => `Failed to read from stdin: ${message}`);
+}
+
+export async function promptHidden(prompt: string): Promise<Result<string>> {
+  if (!process.stdin.isTTY) {
+    return fail(`Interactive prompt requires a TTY (prompt: ${prompt})`);
+  }
+
+  return new Promise<Result<string>>((resolve) => {
+    const input = process.stdin;
+    const output = process.stderr;
+    const previousRawMode = input.isRaw;
+    let value = '';
+    let finished = false;
+
+    function onData(chunk: string): void {
+      for (const char of chunk) {
+        if (char === '\r' || char === '\n') {
+          finish(succeed(value));
+          return;
+        }
+        if (char === '\u0003') {
+          finish(fail('Prompt cancelled'));
+          return;
+        }
+        if (char === '\u007f' || char === '\b') {
+          value = value.slice(0, -1);
+          continue;
+        }
+        value += char;
+      }
+    }
+
+    function finish(result: Result<string>): void {
+      if (finished) {
+        return;
+      }
+      finished = true;
+      input.off('data', onData);
+      if (input.isTTY && input.isRaw && !previousRawMode) {
+        input.setRawMode(false);
+      }
+      input.pause();
+      output.write('\n');
+      resolve(result);
+    }
+
+    output.write(prompt);
+    input.setRawMode(true);
+    input.setEncoding('utf8');
+    input.resume();
+    input.on('data', onData);
+  });
+}
+
+export async function promptVisible(prompt: string): Promise<Result<string>> {
+  if (!process.stdin.isTTY) {
+    return fail(`Interactive prompt requires a TTY (prompt: ${prompt})`);
+  }
+
+  return new Promise<Result<string>>((resolve) => {
+    const input = process.stdin;
+    const output = process.stderr;
+    const interfaceInstance = readline.createInterface({ input, output, terminal: true });
+    let finished = false;
+
+    function finish(result: Result<string>): void {
+      if (finished) {
+        return;
+      }
+
+      finished = true;
+      interfaceInstance.close();
+      output.write('\n');
+      resolve(result);
+    }
+
+    interfaceInstance.on('SIGINT', () => {
+      finish(fail('Prompt cancelled'));
+    });
+
+    interfaceInstance.question(prompt, (answer: string) => {
+      finish(succeed(answer));
+    });
+  });
+}
+
+export async function copyTextToClipboard(text: string): Promise<Result<'copied'>> {
+  const result = await captureAsyncResult(async () => {
+    await clipboardy.write(text);
+    return 'copied' as const;
+  });
+
+  return result.withErrorFormat((message: string) => `Failed to copy to clipboard: ${message}`);
+}

package/src/keystore.ts

@@ -0,0 +1,196 @@
+import fs from 'fs';
+
+import { CryptoUtils } from '@fgv/ts-extras';
+import { Result, captureResult, fail, succeed } from '@fgv/ts-utils';
+
+import { defaultKeystorePath, readTextFile, resolvePath, writeTextFile } from './io';
+
+export interface IKeystoreOpenResult {
+  readonly path: string;
+  readonly keystore: CryptoUtils.KeyStore.KeyStore;
+}
+
+export interface ISecretWriteOptions {
+  readonly description?: string;
+  readonly replace?: boolean;
+}
+
+export function resolveKeystorePath(filePath?: string): string {
+  return resolvePath(filePath ?? defaultKeystorePath());
+}
+
+export function loadKeystoreFile(resolvedPath: string): Result<CryptoUtils.KeyStore.IKeyStoreFile> {
+  return readTextFile(resolvedPath)
+    .onSuccess((contents) =>
+      captureResult(() => JSON.parse(contents)).withErrorFormat(
+        (msg) => `Invalid keystore file '${resolvedPath}': ${msg}`
+      )
+    )
+    .onSuccess((json) =>
+      CryptoUtils.KeyStore.Converters.keystoreFile
+        .convert(json)
+        .withErrorFormat((msg) => `Invalid keystore file '${resolvedPath}': ${msg}`)
+    );
+}
+
+export function saveKeystoreFile(
+  filePath: string | undefined,
+  keystoreFile: CryptoUtils.KeyStore.IKeyStoreFile
+): Result<string> {
+  const resolvedPath = resolveKeystorePath(filePath);
+  const serialized = `${JSON.stringify(keystoreFile, null, 2)}\n`;
+  return writeTextFile(resolvedPath, serialized);
+}
+
+export async function openKeystore(
+  filePath: string | undefined,
+  password: string
+): Promise<Result<IKeystoreOpenResult>> {
+  const resolvedPath = resolveKeystorePath(filePath);
+  return loadKeystoreFile(resolvedPath)
+    .onSuccess((file) =>
+      CryptoUtils.KeyStore.KeyStore.open({
+        cryptoProvider: CryptoUtils.nodeCryptoProvider,
+        keystoreFile: file
+      })
+    )
+    .thenOnSuccess((store) => store.unlock(password))
+    .onSuccess((keystore) => succeed({ path: resolvedPath, keystore }));
+}
+
+export async function createKeystore(
+  filePath: string | undefined,
+  password: string
+): Promise<Result<IKeystoreOpenResult>> {
+  const resolvedPath = resolveKeystorePath(filePath);
+  if (fs.existsSync(resolvedPath)) {
+    const readable = readTextFile(resolvedPath);
+    if (readable.isFailure()) {
+      return fail(`Keystore file at '${resolvedPath}' exists but cannot be read: ${readable.message}`);
+    }
+    return fail(`Keystore already exists at '${resolvedPath}'`);
+  }
+
+  const created = CryptoUtils.KeyStore.KeyStore.create({
+    cryptoProvider: CryptoUtils.nodeCryptoProvider
+  });
+  if (created.isFailure()) {
+    return fail(`Failed to create keystore: ${created.message}`);
+  }
+
+  const keystore = created.value;
+  const initialized = await keystore.initialize(password);
+  if (initialized.isFailure()) {
+    return fail(`Failed to initialize keystore: ${initialized.message}`);
+  }
+
+  const saved = await keystore.save(password);
+  if (saved.isFailure()) {
+    return fail(`Failed to save keystore: ${saved.message}`);
+  }
+
+  const savedFile = saveKeystoreFile(resolvedPath, saved.value);
+  if (savedFile.isFailure()) {
+    return fail(`Failed to write keystore file: ${savedFile.message}`);
+  }
+
+  return succeed({ path: resolvedPath, keystore });
+}
+
+export async function changeKeystorePassword(
+  filePath: string | undefined,
+  currentPassword: string,
+  nextPassword: string
+): Promise<Result<IKeystoreOpenResult>> {
+  const opened = await openKeystore(filePath, currentPassword);
+  if (opened.isFailure()) {
+    return fail(opened.message);
+  }
+
+  const changed = await opened.value.keystore.changePassword(currentPassword, nextPassword);
+  if (changed.isFailure()) {
+    return fail(`Failed to change password: ${changed.message}`);
+  }
+
+  const saved = await opened.value.keystore.save(nextPassword);
+  if (saved.isFailure()) {
+    return fail(`Failed to save keystore: ${saved.message}`);
+  }
+
+  const persisted = saveKeystoreFile(opened.value.path, saved.value);
+  if (persisted.isFailure()) {
+    return fail(`Failed to write keystore file: ${persisted.message}`);
+  }
+
+  return succeed(opened.value);
+}
+
+export async function storeSecret(
+  filePath: string | undefined,
+  password: string,
+  name: string,
+  value: string,
+  options?: ISecretWriteOptions
+): Promise<Result<string>> {
+  const opened = await openKeystore(filePath, password);
+  if (opened.isFailure()) {
+    return fail(opened.message);
+  }
+
+  const writeResult = await opened.value.keystore.importApiKey(name, value, {
+    description: options?.description,
+    replace: options?.replace
+  });
+  if (writeResult.isFailure()) {
+    return fail(`Failed to store secret '${name}': ${writeResult.message}`);
+  }
+
+  const saved = await opened.value.keystore.save(password);
+  if (saved.isFailure()) {
+    return fail(`Failed to save keystore: ${saved.message}`);
+  }
+
+  return saveKeystoreFile(opened.value.path, saved.value).withErrorFormat(
+    (msg) => `Failed to write keystore file: ${msg}`
+  );
+}
+
+export async function readSecret(
+  filePath: string | undefined,
+  password: string,
+  name: string
+): Promise<Result<string>> {
+  return (await openKeystore(filePath, password)).onSuccess((opened) => opened.keystore.getApiKey(name));
+}
+
+export async function listSecrets(
+  filePath: string | undefined,
+  password: string
+): Promise<Result<readonly string[]>> {
+  return (await openKeystore(filePath, password)).onSuccess((opened) => opened.keystore.listSecrets());
+}
+
+export async function removeSecret(
+  filePath: string | undefined,
+  password: string,
+  name: string
+): Promise<Result<string>> {
+  const opened = await openKeystore(filePath, password);
+  if (opened.isFailure()) {
+    return fail(opened.message);
+  }
+
+  const removed = await opened.value.keystore.removeSecret(name);
+  if (removed.isFailure()) {
+    return fail(`Failed to remove secret '${name}': ${removed.message}`);
+  }
+
+  const saved = await opened.value.keystore.save(password);
+  if (saved.isFailure()) {
+    return fail(`Failed to save keystore: ${saved.message}`);
+  }
+
+  return saveKeystoreFile(opened.value.path, saved.value).withErrorFormat(
+    (msg) => `Failed to write keystore file: ${msg}`
+  );
+}

package/src/template.ts

@@ -0,0 +1,61 @@
+import { Mustache } from '@fgv/ts-extras';
+import { Result, fail, succeed } from '@fgv/ts-utils';
+
+// Mustache is used only for parsing/variable extraction. Rendering is done via regex
+// because Mustache's renderer HTML-escapes output, but we need shell-quoting instead.
+const TEMPLATE_VARIABLE_PATTERN: RegExp = /\{\{\{?\s*(?:&\s*)?([^{}&\s]+)\s*\}?\}\}/g;
+
+function shellEscape(value: string): string {
+  if (value.length === 0) {
+    return "''";
+  }
+
+  return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+
+function isSupportedToken(tokenType: string): boolean {
+  return tokenType === 'name' || tokenType === '&';
+}
+
+export function extractTemplateVariables(template: string): Result<readonly string[]> {
+  return Mustache.MustacheTemplate.create(template).onSuccess((parsed) => {
+    const variables = parsed.extractVariables();
+    const unsupported = variables.find((variable) => !isSupportedToken(variable.tokenType));
+    if (unsupported) {
+      return fail(
+        `Unsupported template token '${unsupported.tokenType}' for variable '${unsupported.name}'. ` +
+          'Only simple variable substitutions are supported in v1.'
+      );
+    }
+
+    return succeed(parsed.extractVariableNames());
+  });
+}
+
+export function renderShellTemplate(
+  template: string,
+  context: Readonly<Record<string, string>>
+): Result<string> {
+  return extractTemplateVariables(template).onSuccess((variables) => {
+    for (const variable of variables) {
+      if (!Object.prototype.hasOwnProperty.call(context, variable)) {
+        return fail(`Missing template variable '${variable}'`);
+      }
+    }
+
+    return succeed(
+      template.replace(TEMPLATE_VARIABLE_PATTERN, (__: string, rawName: string) => {
+        const name = rawName.trim();
+        const value = context[name];
+        if (value === undefined) {
+          return '';
+        }
+        return shellEscape(value);
+      })
+    );
+  });
+}
+
+export function shellQuote(value: string): string {
+  return shellEscape(value);
+}

package/test/mocks/clipboardy.js

@@ -0,0 +1,5 @@
+module.exports = {
+  write: async function write() {
+    return undefined;
+  }
+};

package/test/unit/app.test.ts

@@ -0,0 +1,112 @@
+jest.mock('../../src/io', () => {
+  const actual = jest.requireActual('../../src/io') as typeof import('../../src/io');
+
+  return {
+    ...actual,
+    promptHidden: jest.fn(),
+    promptVisible: jest.fn()
+  };
+});
+
+jest.mock('../../src/keystore', () => {
+  const actual = jest.requireActual('../../src/keystore') as typeof import('../../src/keystore');
+
+  return {
+    ...actual,
+    storeSecret: jest.fn()
+  };
+});
+
+import '@fgv/ts-utils-jest';
+
+import { succeed } from '@fgv/ts-utils';
+
+import { KsCli } from '../../src/app';
+import { promptHidden, promptVisible } from '../../src/io';
+import { storeSecret } from '../../src/keystore';
+
+describe('KsCli put command', () => {
+  const promptHiddenMock = jest.mocked(promptHidden);
+  const promptVisibleMock = jest.mocked(promptVisible);
+  const storeSecretMock = jest.mocked(storeSecret);
+  const originalFgvPassword = process.env.FGV_KS_PASSWORD;
+  const originalKsPassword = process.env.KS_PASSWORD;
+
+  beforeEach(() => {
+    process.env.FGV_KS_PASSWORD = 'test-password';
+    delete process.env.KS_PASSWORD;
+
+    promptHiddenMock.mockReset();
+    promptVisibleMock.mockReset();
+    storeSecretMock.mockReset();
+
+    promptHiddenMock.mockResolvedValue(succeed('secret-value'));
+    promptVisibleMock.mockResolvedValue(succeed('secret-name'));
+    storeSecretMock.mockResolvedValue(succeed('/mock/keystore/path'));
+  });
+
+  afterAll(() => {
+    if (originalFgvPassword === undefined) {
+      delete process.env.FGV_KS_PASSWORD;
+    } else {
+      process.env.FGV_KS_PASSWORD = originalFgvPassword;
+    }
+
+    if (originalKsPassword === undefined) {
+      delete process.env.KS_PASSWORD;
+    } else {
+      process.env.KS_PASSWORD = originalKsPassword;
+    }
+  });
+
+  test('prompts for both the secret name and value when no name is provided', async () => {
+    await new KsCli().run(['node', 'ks', 'put']);
+
+    expect(promptVisibleMock).toHaveBeenCalledWith('Secret name: ');
+    expect(promptHiddenMock).toHaveBeenCalledWith('Secret value: ');
+    expect(storeSecretMock).toHaveBeenCalledWith(
+      expect.any(String),
+      'test-password',
+      'secret-name',
+      'secret-value',
+      {
+        description: undefined,
+        replace: false
+      }
+    );
+  });
+
+  test('uses --name and only prompts for the secret value', async () => {
+    await new KsCli().run(['node', 'ks', 'put', '--name', 'api-key']);
+
+    expect(promptVisibleMock).not.toHaveBeenCalled();
+    expect(promptHiddenMock).toHaveBeenCalledWith('Secret value: ');
+    expect(storeSecretMock).toHaveBeenCalledWith(
+      expect.any(String),
+      'test-password',
+      'api-key',
+      'secret-value',
+      {
+        description: undefined,
+        replace: false
+      }
+    );
+  });
+
+  test('continues to accept a positional secret name for compatibility', async () => {
+    await new KsCli().run(['node', 'ks', 'put', 'legacy-key']);
+
+    expect(promptVisibleMock).not.toHaveBeenCalled();
+    expect(promptHiddenMock).toHaveBeenCalledWith('Secret value: ');
+    expect(storeSecretMock).toHaveBeenCalledWith(
+      expect.any(String),
+      'test-password',
+      'legacy-key',
+      'secret-value',
+      {
+        description: undefined,
+        replace: false
+      }
+    );
+  });
+});